@shbernal/ts-xlsx 1.0.0

package/dist/vba/project-editor.js

@@ -0,0 +1,377 @@
+// 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";
+import { VbaAuthorError, VbaParseError } from "./errors.js";
+import { compressContainer, decompressContainer } from "./ms-ovba.js";
+import { parseVbaProject } from "./project.js";
+import { push, u16, u32, utf16le, validateVbaName } from "./vba-encoding.js";
+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_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 module = project.modules.find((m) => m.name.toUpperCase() === nameKey);
+    if (!module)
+        throw new VbaAuthorError(`module '${name}' is not in the VBA project`);
+    if (module.kind !== 'procedural' && module.kind !== 'class') {
+        throw new VbaAuthorError(`cannot remove module '${name}': its kind '${module.kind}' is tied to host linkage this ` +
+            'primitive cannot verify');
+    }
+    const cfb = new CompoundFile(bin);
+    const dirCompressed = cfb.readStream(DIR_STREAM);
+    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);
+    const projectText = cfb.readStream(PROJECT_STREAM);
+    if (projectText) {
+        replacements.set(PROJECT_STREAM, encode(removeProjectStreamLines(decoder.decode(projectText), module.name, module.kind)));
+    }
+    const projectwm = cfb.readStream(PROJECTWM_STREAM);
+    if (projectwm) {
+        replacements.set(PROJECTWM_STREAM, removeProjectwmRecord(projectwm, project.modules.length, module.name, decoder));
+    }
+    const applied = new Set();
+    const withReplacements = replaceStreams(cfb.tree(), replacements, applied);
+    if (!applied.has(DIR_STREAM))
+        throw new VbaParseError("VBA project 'dir' stream is not in the container tree");
+    const removed = new Set();
+    const newTree = removeFromStorage(withReplacements, VBA_STORAGE, module.streamName, removed);
+    if (!removed.has(VBA_STORAGE)) {
+        throw new VbaParseError(`module stream '${module.streamName}' is not in the '${VBA_STORAGE}' storage`);
+    }
+    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());
+    if (!guidMatch)
+        throw new VbaAuthorError(`invalid reference GUID '${ref.guid}'`);
+    const guid = `{${guidMatch.slice(1, 6).join('-').toUpperCase()}}`;
+    for (const [field, value] of [
+        ['majorVersion', ref.majorVersion],
+        ['minorVersion', ref.minorVersion],
+    ]) {
+        if (!Number.isInteger(value) || value < 0 || value > MAX_LIBID_VERSION) {
+            throw new VbaAuthorError(`reference ${field} must be an integer in [0, 0xFFFF], got ${value}`);
+        }
+    }
+    const lcid = ref.lcid ?? 0;
+    if (!Number.isInteger(lcid) || lcid < 0 || lcid > MAX_LIBID_LCID) {
+        throw new VbaAuthorError(`reference lcid must be an integer in [0, 0xFFFFFFFF], got ${lcid}`);
+    }
+    if (ref.path.length === 0 || ref.path.includes('\0') || ref.path.includes('#')) {
+        throw new VbaAuthorError(`invalid reference path '${ref.path}' (must be non-empty and contain no NUL or '#')`);
+    }
+    const displayName = ref.displayName ?? ref.name;
+    if (displayName.length === 0 ||
+        displayName.length > MAX_DISPLAY_NAME_CHARS ||
+        displayName.includes('\0')) {
+        throw new VbaAuthorError(`invalid reference display name '${displayName}'`);
+    }
+    const libid = `*\\G${guid}#${ref.majorVersion.toString(16).toUpperCase()}.` +
+        `${ref.minorVersion.toString(16).toUpperCase()}#${lcid.toString(16).toUpperCase()}` +
+        `#${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);
+    const dirCompressed = cfb.readStream(DIR_STREAM);
+    if (!dirCompressed)
+        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);
+    if (!applied.has(DIR_STREAM))
+        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)];
+    push(r, REC_REFERENCE_NAME, nameBytes);
+    push(r, REC_REFERENCE_NAME_UNICODE, utf16le(ref.name));
+    const libidBytes = [...encode(ref.libid)];
+    push(r, REC_REFERENCE_REGISTERED, [
+        ...u32(libidBytes.length),
+        ...libidBytes,
+        ...u32(0),
+        ...u16(0),
+    ]);
+    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;
+    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; // uncounted VersionMinor (u16)
+        if (id === REC_MODULES_COUNT) {
+            insertAt = recordStart;
+            break;
+        }
+    }
+    if (insertAt < 0)
+        throw new VbaParseError('dir stream is missing MODULES_COUNT');
+    const rec = Uint8Array.from(records);
+    const out = new Uint8Array(dir.length + rec.length);
+    out.set(dir.subarray(0, insertAt), 0);
+    out.set(rec, insertAt);
+    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;
+    let blockStart = -1;
+    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; // uncounted VersionMinor (u16)
+        if (id === REC_MODULES_COUNT) {
+            if (size < 2)
+                throw new VbaParseError('PROJECTMODULES MODULES_COUNT record is malformed');
+            countAt = dataStart;
+        }
+        else if (id === REC_MODULE_NAME) {
+            blockStart = recordStart;
+        }
+        else if (id === REC_MODULE_STREAMNAME) {
+            currentStream = decoder.decode(dir.subarray(dataStart, dataStart + size));
+        }
+        else if (id === REC_MODULE_TERMINATOR) {
+            if (currentStream === streamName) {
+                removeStart = blockStart;
+                removeEnd = pos;
+            }
+            currentStream = undefined;
+            blockStart = -1;
+        }
+    }
+    if (countAt < 0)
+        throw new VbaParseError('dir stream is missing MODULES_COUNT');
+    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);
+    const newCount = readU16(out, countAt) - 1;
+    out[countAt] = newCount & 0xff;
+    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/);
+    const declLine = `${kind === 'procedural' ? 'Module' : 'Class'}=${name}`;
+    const declIndex = lines.indexOf(declLine);
+    if (declIndex >= 0)
+        lines.splice(declIndex, 1);
+    const wsIndex = lines.findIndex((l) => l.trim() === '[Workspace]');
+    if (wsIndex >= 0) {
+        for (let i = wsIndex + 1; i < lines.length; i++) {
+            const l = lines[i];
+            if (l.trim() === '' || l.startsWith('['))
+                break;
+            if (l.startsWith(`${name}=`)) {
+                lines.splice(i, 1);
+                break;
+            }
+        }
+    }
+    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;
+    let removeEnd = -1;
+    for (let i = 0; i < existingModuleCount; i++) {
+        const recordStart = pos;
+        const mbcsEnd = wm.indexOf(0x00, pos);
+        if (mbcsEnd < 0)
+            throw new VbaParseError('PROJECTwm record is missing its MBCS name terminator');
+        const mbcsName = decoder.decode(wm.subarray(pos, mbcsEnd));
+        pos = mbcsEnd + 1;
+        let utf16End = pos;
+        while (utf16End + 1 < wm.length && (wm[utf16End] !== 0 || wm[utf16End + 1] !== 0))
+            utf16End += 2;
+        if (utf16End + 1 >= wm.length) {
+            throw new VbaParseError('PROJECTwm record is missing its Unicode name terminator');
+        }
+        pos = utf16End + 2;
+        if (mbcsName === name) {
+            removeStart = recordStart;
+            removeEnd = pos;
+        }
+    }
+    if (removeStart < 0 || removeEnd < 0) {
+        throw new VbaParseError(`module '${name}' not found in the PROJECTwm stream`);
+    }
+    const out = new Uint8Array(wm.length - (removeEnd - removeStart));
+    out.set(wm.subarray(0, removeStart), 0);
+    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)
+            return n;
+        const children = removeFromStorage(n.children, storageName, streamName, removed);
+        if (n.name === storageName && !removed.has(storageName)) {
+            const filtered = children.filter((c) => !('data' in c && c.name === streamName));
+            if (filtered.length !== children.length)
+                removed.add(storageName);
+            return { name: n.name, children: filtered };
+        }
+        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) {
+            const data = replacements.get(node.name);
+            if (data !== undefined) {
+                applied.add(node.name);
+                return { name: node.name, data };
+            }
+            return node;
+        }
+        return { name: node.name, children: replaceStreams(node.children, replacements, applied) };
+    });
+}
+function readU16(buf, at) {
+    return buf[at] | (buf[at + 1] << 8);
+}
+function readU32(buf, at) {
+    return ((buf[at] |
+        (buf[at + 1] << 8) |
+        (buf[at + 2] << 16) |
+        (buf[at + 3] << 24)) >>>
+        0);
+}

package/dist/vba/project.d.ts

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

package/dist/vba/project.js

@@ -0,0 +1,160 @@
+// 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;
+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);
+    const dirCompressed = cfb.readStream('dir');
+    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.
+    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);
+        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; // uncounted VersionMinor (u16)
+        switch (id) {
+            case REC_PROJECT_CODEPAGE:
+                if (size >= 2)
+                    codePage = readU16(dir, dataStart);
+                break;
+            case REC_MODULE_NAME:
+                pending.name = dir.subarray(dataStart, dataStart + size);
+                break;
+            case REC_MODULE_STREAMNAME:
+                pending.streamName = dir.subarray(dataStart, dataStart + size);
+                break;
+            case REC_MODULE_TYPE_PROCEDURAL:
+                pending.documentType = false;
+                break;
+            case REC_MODULE_TYPE_DOCUMENT:
+                pending.documentType = true;
+                break;
+            case REC_MODULE_OFFSET:
+                if (size >= 4)
+                    pending.offset = readU32(dir, dataStart);
+                break;
+            case REC_MODULE_TERMINATOR:
+                if (pending.streamName !== undefined && pending.offset !== undefined)
+                    rawModules.push(pending);
+                pending = {};
+                break;
+            default:
+                break;
+        }
+    }
+    const decoder = decoderForCodePage(codePage);
+    const kindByName = readProjectStreamKinds(cfb, decoder);
+    const modules = rawModules.map((m) => {
+        const streamName = decoder.decode(m.streamName);
+        const name = m.name !== undefined ? decoder.decode(m.name) : streamName;
+        const kind = kindByName.get(name) ?? (m.documentType ? 'document' : 'procedural');
+        return {
+            name,
+            streamName,
+            kind,
+            source: readModuleSource(cfb, streamName, m.offset, decoder),
+        };
+    });
+    return { codePage, modules };
+}
+function readModuleSource(cfb, streamName, textOffset, decoder) {
+    const stream = cfb.readStream(streamName);
+    if (!stream)
+        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');
+    if (!stream)
+        return kinds;
+    const text = decoder.decode(stream);
+    const keyword = {
+        Document: 'document',
+        Module: 'procedural',
+        Class: 'class',
+        BaseClass: 'designer',
+    };
+    for (const line of text.split(/\r\n|\r|\n/)) {
+        const eq = line.indexOf('=');
+        if (eq < 0)
+            continue;
+        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);
+    }
+    return kinds;
+}
+function readU16(buf, at) {
+    return buf[at] | (buf[at + 1] << 8);
+}
+function readU32(buf, at) {
+    return ((buf[at] |
+        (buf[at + 1] << 8) |
+        (buf[at + 2] << 16) |
+        (buf[at + 3] << 24)) >>>
+        0);
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+export declare function validateVbaName(name: string, what: 'project' | 'module' | 'reference'): void;
+/** Append one `dir`-stream TLV record (Id, Size, data) to `out`. */
+export declare function push(out: number[], id: number, data: number[]): void;
+export declare function u16(n: number): number[];
+export declare function u32(n: number): number[];
+/** A name as NUL-free UTF-16LE code units — the encoding [MS-OVBA] uses for every "Unicode" name field. */
+export declare function utf16le(s: string): number[];

package/dist/vba/vba-encoding.js

@@ -0,0 +1,39 @@
+// 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.
+ */
+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);
+}
+export function u16(n) {
+    return [n & 0xff, (n >> 8) & 0xff];
+}
+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++)
+        out.push(...u16(s.charCodeAt(i)));
+    return out;
+}

package/dist/xml/errors.d.ts

@@ -0,0 +1,15 @@
+import { XlsxError } from '../errors.ts';
+/**
+ * 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 declare class XmlParseError extends XlsxError {
+    readonly name = "XmlParseError";
+    readonly code = "malformed-input";
+}