@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/dist/vba/project-editor.js

@@ -1,14 +1,3 @@
-// Structural edits to an existing `vbaProject.bin` that do NOT touch any module's compiled p-code:
-// remove a standard module, or add a registered library reference. Each is a surgical splice — parse the
-// original container, rebuild its whole storage/stream tree, and change only the `dir` records (and, for
-// a removal, the `PROJECT`/`PROJECTwm` text) the edit demands. Every module stream, `_VBA_PROJECT`, and
-// every untouched record rides through byte-for-byte; preservation is by *not touching* them.
-//
-// Authoring or editing module SOURCE is deliberately NOT here. Excel does not recompile from source on
-// open — a module runs the p-code it ships, and only a real Excel can produce genuinely source-matched
-// p-code — so source authoring/editing lives in the offline `tools/vba-compiler` (VBIDE), not in this
-// pure-TS path (ADR 0019). These splices are safe precisely because they leave every module's p-code
-// exactly as its own compiler wrote it.
 import { CompoundFile } from './cfb.js';
 import { writeCompoundFile } from './cfb-writer.js';
 import { decoderForCodePage, encoderForCodePage } from './codepage.js';
@@ -20,40 +9,17 @@ const DIR_STREAM = 'dir';
 const PROJECT_STREAM = 'PROJECT';
 const PROJECTWM_STREAM = 'PROJECTwm';
 const VBA_STORAGE = 'VBA';
-// `dir`-record ids the remove-module splice reads to delimit a module's record block ([MS-OVBA] 2.3.4.2);
-// every other record is preserved verbatim. MODULES_COUNT is decremented as a block is removed.
 const REC_MODULE_NAME = 0x0019;
 const REC_MODULE_STREAMNAME = 0x001a;
 const REC_MODULE_TERMINATOR = 0x002b;
-const REC_PROJECT_VERSION = 0x0009; // its uncounted 2-byte VersionMinor trails the counted payload
+const REC_PROJECT_VERSION = 0x0009;
 const REC_MODULES_COUNT = 0x000f;
-// `dir`-record ids the add-reference splice builds ([MS-OVBA] 2.3.4.2.2). REFERENCENAME's Unicode half
-// is a *literal* 0x003E marker, not a nested record id — but it is laid out as its own Id+Size+data TLV,
-// so a generic walk (and this splice) sees REFERENCENAME as two chained records, exactly like
-// MODULE_NAME/MODULE_NAME_UNICODE. Verified against a real Excel-authored dir stream (2026-07-23).
 const REC_REFERENCE_NAME = 0x0016;
 const REC_REFERENCE_NAME_UNICODE = 0x003e;
 const REC_REFERENCE_REGISTERED = 0x000d;
-/**
- * Remove a standard module from an existing `vbaProject.bin`, returning new bytes that carry every
- * remaining module, reference, and host-info record unchanged. It drops the module's `VBA/<name>`
- * 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.
- * `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
- * the offline `tools/vba-compiler` (in-place mode), which drives the real host.
- *
- * @throws {VbaParseError} if `bin` is not a parseable VBA project (validated before any edit).
- * @throws {VbaAuthorError} if `name` is not in the project, or names a `document`/`designer` module.
- */
 export function removeVbaModule(bin, name) {
-    // Parse fail-closed first: validates the container and resolves the module's kind/stream name, so
-    // nothing is mutated on a bad input or an unsupported module kind.
     const project = parseVbaProject(bin);
-    const nameKey = name.toUpperCase(); // VBA names are case-insensitive
+    const nameKey = name.toUpperCase();
     const module = project.modules.find((m) => m.name.toUpperCase() === nameKey);
     if (!module)
         throw new VbaAuthorError(`module '${name}' is not in the VBA project`);
@@ -66,11 +32,6 @@ export function removeVbaModule(bin, name) {
     if (!dirCompressed)
         throw new VbaParseError("VBA project has no 'dir' stream");
     const patchedDir = removeModuleDirRecord(decompressContainer(dirCompressed), module.streamName, project.codePage);
-    // Leave _VBA_PROJECT untouched. Resetting it to an "unmatchable version" cookie does NOT force Excel
-    // to recompile from source (Excel runs the p-code as-is); on a project that carries real p-code the
-    // reset actively crashes the VBA load (verified 2026-07-24, ADR 0019). The surviving modules keep
-    // their own compiled p-code; the `dir` stream — authoritative for the module list — no longer names
-    // the removed module, which is what makes the removal take.
     const replacements = new Map([[DIR_STREAM, compressContainer(patchedDir)]]);
     const decoder = decoderForCodePage(project.codePage);
     const encode = encoderForCodePage(project.codePage);
@@ -93,17 +54,10 @@ export function removeVbaModule(bin, name) {
     }
     return writeCompoundFile(newTree);
 }
-// LibidMajorVersion/LibidMinorVersion ([MS-OVBA] 2.1.1.8): 1*4HEXDIG, so at most 0xFFFF.
 const MAX_LIBID_VERSION = 0xffff;
-// LibidLcid: 1*8HEXDIG, so at most 0xFFFFFFFF (practically always 0 — locale-neutral).
 const MAX_LIBID_LCID = 0xffffffff;
-// LibidRegName: *255(%x01-FF) — at most 255 bytes, never NUL.
 const MAX_DISPLAY_NAME_CHARS = 255;
 const GUID_PATTERN = /^\{?([0-9A-Fa-f]{8})-([0-9A-Fa-f]{4})-([0-9A-Fa-f]{4})-([0-9A-Fa-f]{4})-([0-9A-Fa-f]{12})\}?$/;
-// Validate every field fail-closed and assemble the Libid string ([MS-OVBA] 2.1.1.8 LibidReference ABNF:
-// `*\G{GUID}#Major.Minor#LCID#Path#RegName`, hex digit strings with no `0x` prefix) — confirmed
-// byte-for-byte against a real Excel-authored reference (2026-07-23):
-// `*\G{420B2830-E718-11CF-893D-00A0C9054228}#1.0#0#C:\Windows\System32\scrrun.dll#Microsoft Scripting Runtime`.
 function normalizeReference(ref) {
     validateVbaName(ref.name, 'reference');
     const guidMatch = GUID_PATTERN.exec(ref.guid.trim());
@@ -136,22 +90,8 @@ function normalizeReference(ref) {
         `#${ref.path}#${displayName}`;
     return { name: ref.name, libid };
 }
-/**
- * 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
- * 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
- * Excel-authored project).
- *
- * @throws {VbaParseError} if `bin` is not a parseable VBA project (validated before any edit).
- * @throws {VbaAuthorError} if any field of `ref` is invalid (see {@link VbaLibraryReference}), or the
- *   assembled reference text has a character the project's code page cannot represent.
- */
 export function addVbaReference(bin, ref) {
     const normalized = normalizeReference(ref);
-    // Parse fail-closed first: validates the container before any mutation.
     const project = parseVbaProject(bin);
     const encode = encoderForCodePage(project.codePage);
     const cfb = new CompoundFile(bin);
@@ -160,8 +100,6 @@ export function addVbaReference(bin, ref) {
         throw new VbaParseError("VBA project has no 'dir' stream");
     const records = buildReferenceDirRecords(normalized, encode);
     const patchedDir = insertReferenceDirRecords(decompressContainer(dirCompressed), records);
-    // Leave _VBA_PROJECT untouched — see the note in removeVbaModule. The new reference is unused by the
-    // existing modules' p-code, so they load and run unchanged; only the `dir` reference array grows.
     const replacements = new Map([[DIR_STREAM, compressContainer(patchedDir)]]);
     const applied = new Set();
     const newTree = replaceStreams(cfb.tree(), replacements, applied);
@@ -169,9 +107,6 @@ export function addVbaReference(bin, ref) {
         throw new VbaParseError("VBA project 'dir' stream is not in the container tree");
     return writeCompoundFile(newTree);
 }
-// Build the REFERENCENAME + REFERENCEREGISTERED record bytes ([MS-OVBA] 2.3.4.2.2.2 / .2.2.5) for one
-// reference. REFERENCENAME's MBCS/Unicode name pair mirrors MODULE_NAME/MODULE_NAME_UNICODE's shape;
-// REFERENCEREGISTERED is one record carrying SizeOfLibid + Libid + two zero Reserved fields.
 function buildReferenceDirRecords(ref, encode) {
     const r = [];
     const nameBytes = [...encode(ref.name)];
@@ -186,10 +121,6 @@ function buildReferenceDirRecords(ref, encode) {
     ]);
     return r;
 }
-// Insert new reference dir records right before MODULES_COUNT (0x000f) — the reference array has no
-// explicit count field; MODULES_COUNT is simply the next record once the last reference ends (confirmed
-// against a real Excel-authored dir stream). Every other record — other references, all modules — rides
-// through unchanged.
 function insertReferenceDirRecords(dir, records) {
     let insertAt = -1;
     let pos = 0;
@@ -203,7 +134,7 @@ function insertReferenceDirRecords(dir, records) {
         }
         pos = dataStart + size;
         if (id === REC_PROJECT_VERSION)
-            pos += 2; // uncounted VersionMinor (u16)
+            pos += 2;
         if (id === REC_MODULES_COUNT) {
             insertAt = recordStart;
             break;
@@ -218,11 +149,6 @@ function insertReferenceDirRecords(dir, records) {
     out.set(dir.subarray(insertAt), insertAt + rec.length);
     return out;
 }
-// Remove one module's MODULE record block from a decompressed `dir` stream, and decrement MODULES_COUNT.
-// A block runs from its MODULE_NAME record (which always opens the block — mirrors buildModuleDirRecord's
-// emission order) through its own MODULE_TERMINATOR, identified by matching MODULE_STREAMNAME against
-// `streamName`. Every other record — PROJECTREFERENCES, other modules, project-level fields — is carried
-// through untouched.
 function removeModuleDirRecord(dir, streamName, codePage) {
     const decoder = decoderForCodePage(codePage);
     let countAt = -1;
@@ -241,7 +167,7 @@ function removeModuleDirRecord(dir, streamName, codePage) {
         }
         pos = dataStart + size;
         if (id === REC_PROJECT_VERSION)
-            pos += 2; // uncounted VersionMinor (u16)
+            pos += 2;
         if (id === REC_MODULES_COUNT) {
             if (size < 2)
                 throw new VbaParseError('PROJECTMODULES MODULES_COUNT record is malformed');
@@ -267,7 +193,6 @@ function removeModuleDirRecord(dir, streamName, codePage) {
     if (removeStart < 0 || removeEnd < 0) {
         throw new VbaParseError(`module stream '${streamName}' not found in the dir stream`);
     }
-    // MODULES_COUNT always precedes every module block, so countAt is unaffected by removing bytes after it.
     const out = new Uint8Array(dir.length - (removeEnd - removeStart));
     out.set(dir.subarray(0, removeStart), 0);
     out.set(dir.subarray(removeEnd), removeStart);
@@ -276,8 +201,6 @@ function removeModuleDirRecord(dir, streamName, codePage) {
     out[countAt + 1] = (newCount >> 8) & 0xff;
     return out;
 }
-// Remove a module's declaration line (`Module=`/`Class=`) and its workspace line from the `PROJECT` text
-// stream — the inverse of insertProjectStreamLines. Every other line is left exactly as it was.
 function removeProjectStreamLines(text, name, kind) {
     const eol = text.includes('\r\n') ? '\r\n' : '\n';
     const lines = text.split(/\r\n|\r|\n/);
@@ -299,9 +222,6 @@ function removeProjectStreamLines(text, name, kind) {
     }
     return lines.join(eol);
 }
-// Remove a module's (MBCS name, UTF-16 name) pair from the binary PROJECTwm stream — the inverse of
-// insertProjectwmRecord. `existingModuleCount` (from the already fail-closed-parsed project, before
-// removal) bounds the walk to the module records, so it never mistakes the terminator for a record.
 function removeProjectwmRecord(wm, existingModuleCount, name, decoder) {
     let pos = 0;
     let removeStart = -1;
@@ -333,9 +253,6 @@ function removeProjectwmRecord(wm, existingModuleCount, name, decoder) {
     out.set(wm.subarray(removeEnd), removeStart);
     return out;
 }
-// Remove the first direct child stream named `streamName` from the first storage named `storageName`
-// found in the tree (depth-first), marking `storageName` in `removed` once done. The inverse of
-// insertIntoStorage.
 function removeFromStorage(nodes, storageName, streamName, removed) {
     return nodes.map((n) => {
         if ('data' in n)
@@ -350,8 +267,6 @@ function removeFromStorage(nodes, storageName, streamName, removed) {
         return { name: n.name, children };
     });
 }
-// Rebuild the node tree, swapping any stream whose name has a replacement. Non-stream nodes (storages)
-// recurse; everything without a replacement is carried through byte-for-byte.
 function replaceStreams(nodes, replacements, applied) {
     return nodes.map((node) => {
         if ('data' in node) {

package/dist/vba/project.js

@@ -1,41 +1,18 @@
-// Turn a raw `vbaProject.bin` into readable module source.
-//
-// Pipeline ([MS-OVBA] 2.3.4.2): the CFB container holds a `VBA/dir` stream (itself MS-OVBA compressed)
-// that lists each module's stream name, its code page, and the byte offset in that module's stream
-// where the compressed source text begins — past the p-code / PerformanceCache. We decompress `dir`,
-// read those facts, then decompress each module stream from its text offset and decode with the
-// project code page. The p-code is version-specific and deliberately not exposed; a reader wants source.
 import { CompoundFile } from './cfb.js';
 import { decoderForCodePage } from './codepage.js';
 import { VbaParseError } from './errors.js';
 import { decompressContainer } from './ms-ovba.js';
-// The OPC packaging identity of a workbook's VBA project — the relationship Type URI Excel wires it
-// under, the content type its `.bin` part declares, and the canonical package path. These are the
-// facts an authoring path needs to attach a macro blob so the writer emits a valid macro-enabled
-// package; the reader matches the same relationship type by suffix (`isPreservedWorkbookRelType`).
 export const VBA_PROJECT_REL_TYPE = 'http://schemas.microsoft.com/office/2006/relationships/vbaProject';
 export const VBA_PROJECT_CONTENT_TYPE = 'application/vnd.ms-office.vbaProject';
 export const VBA_PROJECT_PART_PATH = 'xl/vbaProject.bin';
-// A signature part is matched by the FINAL segment of its relationship Type, not the whole URI: the
-// segment (`vbaProjectSignature{,Agile,V3}`) names the generation, while the year the URI carries
-// (2006 / 2014 / 2020) is incidental and varies. The closure walk already carries any such part
-// through verbatim regardless of type, so recognising the generation token is all detection needs —
-// no exact URI to pin, and a future scheme this map does not know stays preserved but unreported.
 const SIGNATURE_KIND_BY_REL_SEGMENT = {
     vbaProjectSignature: 'legacy',
     vbaProjectSignatureAgile: 'agile',
     vbaProjectSignatureV3: 'v3',
 };
-/**
- * The VBA-signature generation a relationship Type names, or `undefined` if it is not a signature
- * relationship. Keys off the Type's final path segment, so it is independent of the year the URI
- * carries (`.../office/2006/...` vs `.../2014/...` vs `.../2020/...`).
- */
 export function vbaProjectSignatureKind(relType) {
     return SIGNATURE_KIND_BY_REL_SEGMENT[relType.slice(relType.lastIndexOf('/') + 1)];
 }
-// `dir`-stream record ids we consume ([MS-OVBA] 2.3.4.2). Every other record is skipped by the uniform
-// TLV walk; its Size field already accounts for its payload, so skipping is just advancing past it.
 const REC_PROJECT_CODEPAGE = 0x0003;
 const REC_MODULE_NAME = 0x0019;
 const REC_MODULE_STREAMNAME = 0x001a;
@@ -43,9 +20,6 @@ const REC_MODULE_TYPE_PROCEDURAL = 0x0021;
 const REC_MODULE_TYPE_DOCUMENT = 0x0022;
 const REC_MODULE_OFFSET = 0x0031;
 const REC_MODULE_TERMINATOR = 0x002b;
-// PROJECTVERSION carries VersionMajor (u32) + VersionMinor (u16) after its fixed Size=4 field, but Size
-// only accounts for the 4-byte major. The extra 2-byte minor is uncounted, so a uniform TLV walk
-// misaligns here by 2 bytes unless it is skipped explicitly.
 const REC_PROJECT_VERSION = 0x0009;
 export function parseVbaProject(bin) {
     const cfb = new CompoundFile(bin);
@@ -53,10 +27,9 @@ export function parseVbaProject(bin) {
     if (!dirCompressed)
         throw new VbaParseError("VBA project has no 'dir' stream");
     const dir = decompressContainer(dirCompressed);
-    let codePage = 1252; // Western-European default until PROJECTCODEPAGE says otherwise.
+    let codePage = 1252;
     const rawModules = [];
     let pending = {};
-    // The dir stream is a flat sequence of TLV records: Id(u16) Size(u32) data[Size].
     let pos = 0;
     while (pos + 6 <= dir.length) {
         const id = readU16(dir, pos);
@@ -66,7 +39,7 @@ export function parseVbaProject(bin) {
             throw new VbaParseError(`dir record 0x${id.toString(16)} overruns stream`);
         pos = dataStart + size;
         if (id === REC_PROJECT_VERSION)
-            pos += 2; // uncounted VersionMinor (u16)
+            pos += 2;
         switch (id) {
             case REC_PROJECT_CODEPAGE:
                 if (size >= 2)
@@ -118,10 +91,6 @@ function readModuleSource(cfb, streamName, textOffset, decoder) {
         throw new VbaParseError(`module stream '${streamName}' not found in container`);
     return decoder.decode(decompressContainer(stream, textOffset));
 }
-// The `PROJECT` stream (uncounted, plain MBCS text) declares each module's exact kind by keyword:
-// `Document=`, `Module=` (procedural .bas), `Class=`, `BaseClass=` (designer/UserForm). The `dir`
-// stream's MODULETYPE only distinguishes procedural from non-procedural, so PROJECT refines it. Absent
-// or unparsable PROJECT just falls back to that coarser MODULETYPE classification.
 function readProjectStreamKinds(cfb, decoder) {
     const kinds = new Map();
     const stream = cfb.readStream('PROJECT');
@@ -141,7 +110,6 @@ function readProjectStreamKinds(cfb, decoder) {
         const kind = keyword[line.slice(0, eq)];
         if (kind === undefined)
             continue;
-        // Value is `Name` or `Name/&H00000000` (document modules carry a cookie); take the name.
         const name = (line.slice(eq + 1).split('/')[0] ?? '').trim();
         if (name)
             kinds.set(name, kind);

package/dist/vba/vba-encoding.js

@@ -1,26 +1,11 @@
-// Shared low-level encoders for the VBA `dir` stream and name validation — the primitives the structural
-// splices in `project-editor.ts` build on. ([MS-OVBA] 2.3.4.2 record TLVs, and the VBA identifier rules.)
-//
-// There is no from-scratch `vbaProject.bin` synthesizer here. Excel does not recompile VBA from source
-// on open — a module runs the compiled p-code it ships — so authoring/editing module SOURCE is done by
-// the offline `tools/vba-compiler` (VBIDE), which produces genuinely compiled p-code. This module holds
-// only what the pure-TS structural edits (remove module, add reference) still need (ADR 0019).
 import { VbaAuthorError } from './errors.js';
 const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_]*$/;
-const MAX_NAME_CHARS = 31; // the CFB stream-name limit, and VBA's own module-name limit
-/**
- * Validate a module, project, or reference name against the shared VBA identifier contract: a valid
- * identifier, at most 31 characters (the CFB stream-name limit, which doubles as VBA's own module-name
- * limit). Used by {@link project-editor.ts | project-editor}'s structural edits.
- *
- * @throws {VbaAuthorError} if `name` is not a valid VBA identifier or exceeds 31 characters.
- */
+const MAX_NAME_CHARS = 31;
 export function validateVbaName(name, what) {
     if (!IDENTIFIER.test(name) || name.length > MAX_NAME_CHARS) {
         throw new VbaAuthorError(`invalid ${what} name '${name}' (must be a VBA identifier ≤ 31 chars)`);
     }
 }
-/** Append one `dir`-stream TLV record (Id, Size, data) to `out`. */
 export function push(out, id, data) {
     out.push(...u16(id), ...u32(data.length), ...data);
 }
@@ -30,7 +15,6 @@ export function u16(n) {
 export function u32(n) {
     return [n & 0xff, (n >> 8) & 0xff, (n >> 16) & 0xff, (n >> 24) & 0xff];
 }
-/** A name as NUL-free UTF-16LE code units — the encoding [MS-OVBA] uses for every "Unicode" name field. */
 export function utf16le(s) {
     const out = [];
     for (let i = 0; i < s.length; i++)

package/dist/xml/errors.js

@@ -1,14 +1,4 @@
 import { XlsxError } from '../errors.js';
-/**
- * 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
- * being parsed is almost always a part lifted out of an untrusted `.xlsx`. A caller wrapping
- * `readXlsx` needs to tell "the file I was handed is corrupt" from "something in my own code threw a
- * `SyntaxError`", and a native error gives them no way to. The message still names the construct that
- * did not terminate; only the type changed.
- */
 export class XmlParseError extends XlsxError {
     name = 'XmlParseError';
     code = 'malformed-input';

package/dist/xml/xml-read.js

@@ -1,15 +1,3 @@
-// A lean, hostile-input-safe SAX pull parser for the read path.
-//
-// OOXML uses a small, regular subset of XML, so the reader does not need — and must not
-// pay for — a general-purpose DOM library (see ADR 0004). This scans the source in a
-// single O(n) pass with no recursion, emitting open/text/close events; the OOXML reader
-// consumes them and builds only the model, so peak memory tracks real content rather
-// than document structure.
-//
-// Security posture: entities are *decoded, never expanded*. Only the five predefined
-// entities and numeric character references are recognised; DTDs and `<!ENTITY>`
-// definitions are skipped, so entity-expansion (billion-laughs) and external-entity
-// (XXE) attacks are structurally impossible here, not merely mitigated.
 import { XmlParseError } from './errors.js';
 const PREDEFINED_ENTITIES = {
     amp: '&',
@@ -19,18 +7,12 @@ const PREDEFINED_ENTITIES = {
     apos: "'",
 };
 const ENTITY = /&(#x[0-9a-fA-F]+|#[0-9]+|[a-zA-Z][a-zA-Z0-9]*);/g;
-/**
- * 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
- * to expand it to, and refusing to invent one is what makes entity-expansion attacks
- * impossible.
- */
 export function decodeEntities(value) {
     if (!value.includes('&'))
         return value;
     return value.replace(ENTITY, (match, body) => {
-        if (body.charCodeAt(0) === 0x23 /* # */) {
-            const codePoint = body.charCodeAt(1) === 0x78 /* x */
+        if (body.charCodeAt(0) === 0x23) {
+            const codePoint = body.charCodeAt(1) === 0x78
                 ? parseInt(body.slice(2), 16)
                 : parseInt(body.slice(1), 10);
             if (!Number.isInteger(codePoint) || codePoint < 0 || codePoint > 0x10ffff)
@@ -46,9 +28,6 @@ export function decodeEntities(value) {
         return named ?? match;
     });
 }
-// Attribute values cannot contain their own delimiter and cannot contain a literal `<`,
-// so a delimiter-respecting scan finds a tag's end even when an attribute value holds a
-// `>` (legal but rare). Names may carry a namespace prefix (`r:id`, `xml:space`).
 const ATTRIBUTE = /([^\s=/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
 function parseAttributes(source) {
     const attrs = {};
@@ -61,8 +40,6 @@ function parseAttributes(source) {
     }
     return attrs;
 }
-// Scan to the tag's closing `>`, honouring quoted attribute values so a `>` inside a
-// value does not end the tag prematurely.
 function findTagEnd(source, start) {
     let quote = '';
     for (let i = start + 1; i < source.length; i++) {
@@ -80,8 +57,6 @@ function findTagEnd(source, start) {
     }
     throw new XmlParseError('unterminated tag: missing ">"');
 }
-// A `<!DOCTYPE …>` may contain a bracketed internal subset with its own `>`; balance the
-// brackets so the declaration is skipped whole. We never act on its contents.
 function skipDeclaration(source, start) {
     let depth = 0;
     for (let i = start; i < source.length; i++) {
@@ -95,14 +70,6 @@ function skipDeclaration(source, start) {
     }
     throw new XmlParseError('unterminated markup declaration: missing ">"');
 }
-/**
- * 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.
- *
- * Throws {@link XmlParseError} on malformed markup.
- */
 export function* xmlEvents(source) {
     const length = source.length;
     let i = 0;
@@ -147,7 +114,7 @@ export function* xmlEvents(source) {
         }
         const gt = findTagEnd(source, lt);
         const raw = source.slice(lt + 1, gt);
-        if (raw.charCodeAt(0) === 0x2f /* / */) {
+        if (raw.charCodeAt(0) === 0x2f) {
             yield { kind: 'close', name: raw.slice(1).trim() };
         }
         else {
@@ -161,15 +128,6 @@ export function* xmlEvents(source) {
         i = gt + 1;
     }
 }
-/**
- * Yield each element start in `source` as an {@link OpenElement}, optionally restricted to the given
- * local names. This is the pull shape for the ubiquitous "scan opens, read attributes" pass: a caller
- * writes a plain `for..of` and reads `attrs` directly, instead of threading a mutable accumulator out
- * through a {@link parseXml} `onOpen` closure. With no names every start is yielded; with one or more,
- * only starts whose namespace-stripped name matches one. Text and close events are skipped.
- *
- * Throws {@link XmlParseError} on malformed markup.
- */
 export function* openElements(source, ...localNames) {
     const filter = localNames.length > 0 ? new Set(localNames) : undefined;
     for (const event of xmlEvents(source)) {
@@ -181,15 +139,6 @@ export function* openElements(source, ...localNames) {
         yield { name: event.name, local, attrs: event.attrs };
     }
 }
-/**
- * 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
- * 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.
- */
 export function* closeEmptyElements(events, names) {
     for (const event of events) {
         if (event.kind === 'open' && event.selfClosing && names.has(localName(event.name))) {
@@ -201,11 +150,6 @@ export function* closeEmptyElements(events, names) {
         }
     }
 }
-/**
- * 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.
- * Throws {@link XmlParseError} on malformed markup.
- */
 export function parseXml(source, handlers, options) {
     const events = options?.closeEmptyElements
         ? closeEmptyElements(xmlEvents(source), options.closeEmptyElements)
@@ -224,11 +168,6 @@ export function parseXml(source, handlers, options) {
         }
     }
 }
-// XML end-of-line handling (spec §2.11): a literal CRLF or lone CR in character data is
-// normalized to a single LF, so a value's in-cell line breaks read back identically whatever
-// newline convention the producer wrote. Normalization precedes entity decoding, so a
-// deliberately-encoded carriage return (&#13;) survives it — the escape hatch for a real CR.
-// CDATA is delivered verbatim (it bypasses this), matching the reader's CDATA contract.
 function normalizeLineEndings(chunk) {
     if (!chunk.includes('\r'))
         return chunk;
@@ -242,29 +181,16 @@ function firstWhitespace(source) {
     }
     return -1;
 }
-/** Strip a namespace prefix from a qualified name (`r:id` → `id`, `sheet` → `sheet`). */
 export function localName(qualified) {
     const colon = qualified.indexOf(':');
     return colon === -1 ? qualified : qualified.slice(colon + 1);
 }
-// OOXML spells booleans three ways, and the reader needs all three. A `<b/>`-style font flag
-// defaults to on when present with no value, so its absence is meaningful (`boolPresent`). Most
-// attributes are plain xsd:booleans that are off unless an explicit "1"/"true" turns them on
-// (`boolStrict`). An optional attribute that must round-trip byte-clean has to distinguish absent
-// from present-and-false and drop an unrecognised token rather than coerce it (`boolTristate`).
-/** 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 function boolPresent(val) {
     return val === undefined || (val !== '0' && val !== 'false');
 }
-/** An OOXML boolean that is on only when explicitly `"1"`/`"true"`; anything else — including
- * absence and a truthy-looking `"0"` — is off. */
 export function boolStrict(val) {
     return val === '1' || val === 'true';
 }
-/** 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 function boolTristate(val) {
     if (val === '1' || val === 'true')
         return true;
@@ -272,11 +198,6 @@ export function boolTristate(val) {
         return false;
     return undefined;
 }
-/** Read an operand's text as a number only when it is a canonical decimal literal (optional sign,
- * digits, optional fraction). A cell reference, defined name, expression, or exotically-spelled
- * number (`1E5`, hex) keeps its verbatim text, so it is neither coerced to `NaN` and lost nor
- * re-spelled into a number that would not re-write byte-clean. Callers layer their own type rules
- * (a data-validation `list`/`custom` operand stays a string regardless of what it looks like). */
 export function coerceNumericLiteral(text) {
     const trimmed = text.trim();
     return /^-?\d+(?:\.\d+)?$/.test(trimmed) ? Number(trimmed) : text;

package/dist/xml/xml.js

@@ -1,10 +1,3 @@
-// Minimal XML serialisation helpers for the write path.
-//
-// Writing OOXML needs only correct escaping and well-formed structure; parsing (the
-// reader's concern) is a separate, later decision, so no XML library is on the write
-// path. Escaping is the one hard, security-relevant requirement — an unescaped `<`,
-// `&`, or `"` produces a malformed package a consumer rejects — so it lives here,
-// audited once, rather than sprinkled through the part emitters.
 import { AuthoringError } from '../errors.js';
 const TEXT_ESCAPES = {
     '&': '&amp;',
@@ -21,62 +14,30 @@ const ATTR_ESCAPES = {
     '\r': '&#13;',
     '\t': '&#9;',
 };
-/** Escape a string for use as XML element text. */
 export function escapeText(value) {
     return value.replace(/[&<>]/g, (ch) => TEXT_ESCAPES[ch]);
 }
-/** Escape a string for use inside a double-quoted XML attribute value. */
 export function escapeAttr(value) {
     return value.replace(/[&<>"'\n\r\t]/g, (ch) => ATTR_ESCAPES[ch]);
 }
-/**
- * Whether an element's text must be wrapped with `xml:space="preserve"` to survive a
- * round-trip. Leading/trailing whitespace is otherwise collapsed by consumers, so a
- * string cell value that begins or ends with a space needs the marker.
- */
 export function needsSpacePreserve(value) {
     return value.length > 0 && (value !== value.trim() || /[\n\r\t]/.test(value));
 }
-/**
- * A `<t>` text element carrying an escaped string, marked `xml:space="preserve"` when its
- * whitespace would otherwise be collapsed. Shared by every string-bearing element — a plain
- * inline string cell, a rich-text run — so all decode identically on the way back.
- */
 export function textElement(value) {
     const space = needsSpacePreserve(value) ? ' xml:space="preserve"' : '';
     return `<t${space}>${escapeText(value)}</t>`;
 }
-/**
- * Render a formula operand for serialisation: a number becomes its literal, a string is stripped of
- * the single optional leading '=' an author may write (OOXML stores the expression without it, e.g.
- * `=A1>0` on disk is `A1>0`). The result is unescaped — the caller escapes it for its target,
- * whether that is element text or an attribute value.
- */
 export function stripFormulaEquals(value) {
     if (typeof value === 'number')
         return String(value);
     return value.startsWith('=') ? value.slice(1) : value;
 }
-/**
- * A boolean attribute rendered with a leading space (` name="1"` / ` name="0"`), or '' when the value
- * is undefined. OOXML booleans serialise as 1/0; emitting the explicit `="0"` lets a writer force a
- * flag off against a consumer's default, while an unset (undefined) flag stays out of the element
- * entirely — the two-state-plus-absent contract every flag writer here shares.
- */
 export function boolAttr(name, value) {
     return value === undefined ? '' : ` ${name}="${value ? 1 : 0}"`;
 }
-/**
- * A numeric attribute rendered with a leading space (` name="42"`), or '' when the value is undefined
- * — so a count an author never set stays out of the element rather than fabricating a default.
- */
 export function attr(name, value) {
     return value === undefined ? '' : ` ${name}="${value}"`;
 }
-/**
- * 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`.
- */
 export function numberText(value) {
     if (!Number.isFinite(value)) {
         throw new AuthoringError(`cannot write a non-finite number (${value}) — it has no OOXML representation`);