@shbernal/ts-xlsx 1.0.0

package/dist/vba/cfb-writer.js

@@ -0,0 +1,277 @@
+// 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 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;
+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) => {
+        const entry = {
+            index: entries.length,
+            name,
+            type,
+            startSector,
+            size: 0,
+            left: NOSTREAM,
+            right: NOSTREAM,
+            child: NOSTREAM,
+        };
+        entries.push(entry);
+        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) });
+            }
+            else {
+                const startMini = miniBytes.length / MINI_SECTOR;
+                const numMini = Math.ceil(node.data.length / MINI_SECTOR);
+                for (let k = 0; k < numMini; k++)
+                    miniFat.push(k < numMini - 1 ? startMini + k + 1 : ENDOFCHAIN);
+                miniBytes.push(...node.data, ...new Array(numMini * MINI_SECTOR - node.data.length).fill(0));
+                entry.startSector = startMini;
+            }
+        }
+        else {
+            const entry = addEntry(node.name, TYPE_STORAGE, 0);
+            siblings.push(entry);
+            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);
+        }
+    };
+    validateSiblingNames('Root Entry', root);
+    const rootKids = [];
+    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);
+    const baseSectors = dirSectors +
+        miniFatSectors +
+        miniStreamSectors +
+        bigStreams.reduce((total, big) => total + big.sectors, 0);
+    let fatSectors = 0;
+    let difatSectors = 0;
+    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;
+        if (needFat === fatSectors && needDifat === difatSectors)
+            break;
+        fatSectors = needFat;
+        difatSectors = needDifat;
+    }
+    if (fatSectors > DIFAT_HEADER_SLOTS) {
+        throw new VbaAuthorError(`project needs ${fatSectors} FAT sectors, exceeding the ${DIFAT_HEADER_SLOTS}-sector single-header bound`);
+    }
+    let cursor = 0;
+    const dirStart = cursor;
+    cursor += dirSectors;
+    const miniFatStart = miniFatSectors > 0 ? cursor : ENDOFCHAIN;
+    cursor += miniFatSectors;
+    const miniStreamStart = miniStreamSectors > 0 ? cursor : ENDOFCHAIN;
+    cursor += miniStreamSectors;
+    for (const big of bigStreams) {
+        big.entry.startSector = cursor;
+        cursor += big.sectors;
+    }
+    const fatStart = cursor;
+    cursor += fatSectors;
+    const difatStart = difatSectors > 0 ? cursor : ENDOFCHAIN;
+    cursor += difatSectors;
+    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++)
+            fat[start + k] = k < count - 1 ? start + k + 1 : ENDOFCHAIN;
+    };
+    chainRegion(dirStart, dirSectors);
+    if (miniFatSectors > 0)
+        chainRegion(miniFatStart, miniFatSectors);
+    if (miniStreamSectors > 0)
+        chainRegion(miniStreamStart, miniStreamSectors);
+    for (const big of bigStreams)
+        chainRegion(big.entry.startSector, big.sectors);
+    for (let k = 0; k < fatSectors; k++)
+        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 dv = new DataView(buf.buffer);
+    const at = (sector) => (sector + 1) * SECTOR;
+    writeHeader(dv, {
+        fatSectors,
+        dirStart,
+        miniFatStart,
+        miniFatSectors,
+        difatStart,
+        difatSectors,
+        fatStart,
+    });
+    for (const e of entries)
+        writeDirEntry(dv, at(dirStart) + e.index * DIR_ENTRY_SIZE, e);
+    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++) {
+            const fatIdx = DIFAT_HEADER_SLOTS + d * (FAT_ENTRIES_PER_SECTOR - 1) + i;
+            dv.setUint32(base + i * 4, fatIdx < fatSectors ? fatStart + fatIdx : FREESECT, true);
+        }
+        dv.setUint32(base + (FAT_ENTRIES_PER_SECTOR - 1) * 4, d < difatSectors - 1 ? difatStart + d + 1 : ENDOFCHAIN, true);
+    }
+    return buf;
+}
+function validateSiblingNames(storageName, siblings) {
+    const seen = new Set();
+    for (const node of siblings) {
+        if (node.name.length === 0)
+            throw new VbaAuthorError('entry name must not be empty');
+        if (node.name.length > MAX_NAME_CHARS) {
+            throw new VbaAuthorError(`entry name '${node.name}' exceeds the ${MAX_NAME_CHARS}-character CFB limit`);
+        }
+        if (seen.has(node.name)) {
+            throw new VbaAuthorError(`duplicate entry name '${node.name}' under storage '${storageName}'`);
+        }
+        seen.add(node.name);
+        if (!isStream(node))
+            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;
+        const node = nodes[mid];
+        if (node === undefined)
+            return NOSTREAM;
+        node.left = build(nodes.slice(0, mid));
+        node.right = build(nodes.slice(mid + 1));
+        return node.index;
+    };
+    storage.child = build([...kids].sort((a, b) => compareNames(a.name, b.name)));
+}
+function compareNames(a, b) {
+    if (a.length !== b.length)
+        return a.length - b.length;
+    const ua = a.toUpperCase();
+    const ub = b.toUpperCase();
+    return ua < ub ? -1 : ua > ub ? 1 : 0;
+}
+function writeHeader(dv, p) {
+    dv.setUint32(0, 0xe011cfd0, true); // OLE2 signature (lo/hi)
+    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.setUint32(44, p.fatSectors, true);
+    dv.setUint32(48, p.dirStart, true);
+    dv.setUint32(56, MINI_CUTOFF, true);
+    dv.setUint32(60, p.miniFatStart, true);
+    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);
+    }
+}
+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.setUint8(off + 66, e.type);
+    dv.setUint8(off + 67, COLOR_BLACK);
+    dv.setUint32(off + 68, e.left, true);
+    dv.setUint32(off + 72, e.right, true);
+    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.d.ts

@@ -0,0 +1,16 @@
+import type { CfbNode } from './cfb-writer.ts';
+export declare class CompoundFile {
+    #private;
+    constructor(buf: Uint8Array);
+    /** List every stream/storage name in the directory (order as stored). */
+    names(): string[];
+    /** Read a stream's raw bytes by exact entry name, or `undefined` if absent. */
+    readStream(name: string): Uint8Array | undefined;
+    /**
+     * Reconstruct the container's top-level children as the writer's node shape, recursing into every
+     * storage — so a caller can swap one stream and re-emit the whole hierarchy with {@link writeCompoundFile}.
+     * 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(): CfbNode[];
+}

package/dist/vba/cfb.js

@@ -0,0 +1,324 @@
+// 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;
+const TYPE_STORAGE = 1;
+const TYPE_STREAM = 2;
+const TYPE_ROOT = 5;
+const CFB_SIGNATURE_LO = 0xe011cfd0;
+const CFB_SIGNATURE_HI = 0xe11ab1a1;
+const DIR_ENTRY_SIZE = 128;
+export class CompoundFile {
+    #buf;
+    #view;
+    #sectorSize;
+    #miniSectorSize;
+    #miniCutoff;
+    #maxSector;
+    #fat;
+    #miniFat;
+    #dir;
+    #miniStream;
+    constructor(buf) {
+        this.#buf = buf;
+        this.#view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+        if (buf.length < 512)
+            throw new VbaParseError('compound file shorter than its 512-byte header');
+        if (this.#u32(0) !== CFB_SIGNATURE_LO || this.#u32(4) !== CFB_SIGNATURE_HI) {
+            throw new VbaParseError('not a compound file (bad OLE2 signature)');
+        }
+        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}`);
+        }
+        if (miniSectorShift !== 6)
+            throw new VbaParseError(`unsupported mini-sector shift ${miniSectorShift}`);
+        this.#sectorSize = 1 << sectorShift;
+        this.#miniSectorSize = 1 << miniSectorShift;
+        this.#maxSector = Math.floor(buf.length / this.#sectorSize);
+        const numFatSectors = this.#u32(44);
+        const firstDirSector = this.#u32(48);
+        this.#miniCutoff = this.#u32(56);
+        const firstMiniFatSector = this.#u32(60);
+        const firstDifatSector = this.#u32(68);
+        const numDifatSectors = this.#u32(72);
+        const fatSectorIds = this.#readDifat(numFatSectors, firstDifatSector, numDifatSectors);
+        this.#fat = this.#readFat(fatSectorIds);
+        this.#miniFat = this.#readChainValues(firstMiniFatSector);
+        this.#dir = this.#readDirectory(firstDirSector);
+        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)
+            throw new VbaParseError('compound file has no root storage entry');
+        const root = this.#dir[rootIdx];
+        return this.#buildSiblings(root.child, new Set([rootIdx]));
+    }
+    #buildSiblings(firstChild, seen) {
+        const nodes = [];
+        const walk = (idx) => {
+            if (idx >= MAX_REGULAR_SECTOR)
+                return; // NOSTREAM / terminal marker → no such sibling
+            if (idx >= this.#dir.length)
+                throw new VbaParseError('directory sibling index out of range');
+            if (seen.has(idx))
+                throw new VbaParseError('cycle in directory sibling tree');
+            seen.add(idx);
+            const e = this.#dir[idx];
+            if (e.type === TYPE_EMPTY)
+                throw new VbaParseError('directory tree links an empty entry');
+            walk(e.left);
+            if (e.type === TYPE_STORAGE) {
+                nodes.push({ name: e.name, children: this.#buildSiblings(e.child, seen) });
+            }
+            else {
+                nodes.push({ name: e.name, data: this.#readEntryData(e) });
+            }
+            walk(e.right);
+        };
+        walk(firstChild);
+        return nodes;
+    }
+    #readEntryData(entry) {
+        if (entry.size >= this.#miniCutoff)
+            return this.#readViaFat(entry.startSector, entry.size);
+        return this.#readViaMiniFat(entry.startSector, entry.size);
+    }
+    #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)
+                break;
+            ids.push(v);
+        }
+        const seen = new Set();
+        let sector = firstDifat;
+        const perSector = this.#sectorSize / 4 - 1;
+        for (let s = 0; s < numDifat && sector < MAX_REGULAR_SECTOR; s++) {
+            if (seen.has(sector))
+                throw new VbaParseError('cycle in DIFAT sector chain');
+            seen.add(sector);
+            const base = this.#dataSectorOffset(sector);
+            for (let i = 0; i < perSector; i++) {
+                const v = this.#u32(base + i * 4);
+                if (v < MAX_REGULAR_SECTOR)
+                    ids.push(v);
+            }
+            sector = this.#u32(base + perSector * 4);
+        }
+        return ids;
+    }
+    #readFat(fatSectorIds) {
+        const fat = [];
+        const perSector = this.#sectorSize / 4;
+        for (const sid of fatSectorIds) {
+            const base = this.#dataSectorOffset(sid);
+            for (let i = 0; i < perSector; i++)
+                fat.push(this.#u32(base + i * 4));
+        }
+        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();
+        let sector = firstSector;
+        while (sector < MAX_REGULAR_SECTOR) {
+            if (seen.has(sector))
+                throw new VbaParseError('cycle in mini-FAT sector chain');
+            seen.add(sector);
+            const base = this.#dataSectorOffset(sector);
+            for (let i = 0; i < perSector; i++)
+                values.push(this.#u32(base + i * 4));
+            sector = this.#nextInFat(sector);
+        }
+        return values;
+    }
+    #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 &&
+                type !== TYPE_STORAGE &&
+                type !== TYPE_STREAM &&
+                type !== TYPE_ROOT) {
+                throw new VbaParseError(`directory entry has invalid object type ${type}`);
+            }
+            const left = readU32(raw, off + 68);
+            const right = readU32(raw, off + 72);
+            const child = readU32(raw, off + 76);
+            if (type === TYPE_EMPTY) {
+                entries.push({
+                    name: '',
+                    type,
+                    startSector: 0,
+                    size: 0,
+                    left: NOSTREAM,
+                    right: NOSTREAM,
+                    child: NOSTREAM,
+                });
+                continue;
+            }
+            const nameLen = readU16(raw, off + 64);
+            if (nameLen > 64 || nameLen % 2 !== 0) {
+                throw new VbaParseError(`directory entry has invalid name length ${nameLen}`);
+            }
+            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
+            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;
+        while (sector < MAX_REGULAR_SECTOR) {
+            if (seen.has(sector))
+                throw new VbaParseError('cycle in FAT sector chain');
+            seen.add(sector);
+            const base = this.#dataSectorOffset(sector);
+            chunks.push(this.#buf.subarray(base, base + this.#sectorSize));
+            sector = this.#nextInFat(sector);
+        }
+        return concat(chunks);
+    }
+    #readViaFat(startSector, size) {
+        const chunks = [];
+        const seen = new Set();
+        let sector = startSector;
+        let remaining = size;
+        while (sector < MAX_REGULAR_SECTOR && remaining > 0) {
+            if (seen.has(sector))
+                throw new VbaParseError('cycle in stream FAT chain');
+            seen.add(sector);
+            const base = this.#dataSectorOffset(sector);
+            const take = Math.min(this.#sectorSize, remaining);
+            chunks.push(this.#buf.subarray(base, base + take));
+            remaining -= take;
+            sector = this.#nextInFat(sector);
+        }
+        return concat(chunks);
+    }
+    #readViaMiniFat(startSector, size) {
+        const chunks = [];
+        const seen = new Set();
+        let sector = startSector;
+        let remaining = size;
+        while (sector < MAX_REGULAR_SECTOR && remaining > 0) {
+            if (seen.has(sector))
+                throw new VbaParseError('cycle in stream mini-FAT chain');
+            seen.add(sector);
+            const base = sector * this.#miniSectorSize;
+            const take = Math.min(this.#miniSectorSize, remaining);
+            if (base + take > this.#miniStream.length) {
+                throw new VbaParseError('mini-stream sector runs past end of the mini stream');
+            }
+            chunks.push(this.#miniStream.subarray(base, base + take));
+            remaining -= take;
+            if (sector >= this.#miniFat.length)
+                throw new VbaParseError('mini-FAT index out of range');
+            sector = this.#miniFat[sector];
+        }
+        return concat(chunks);
+    }
+    #nextInFat(sector) {
+        if (sector >= this.#fat.length)
+            throw new VbaParseError('FAT index out of range');
+        return this.#fat[sector];
+    }
+    #dataSectorOffset(sector) {
+        if (sector >= this.#maxSector) {
+            throw new VbaParseError(`sector ${sector} is out of range (file has ${this.#maxSector})`);
+        }
+        const base = (sector + 1) * this.#sectorSize;
+        if (base + this.#sectorSize > this.#buf.length) {
+            throw new VbaParseError(`sector ${sector} runs past end of file`);
+        }
+        return base;
+    }
+    #u16(at) {
+        return this.#view.getUint16(at, true);
+    }
+    #u32(at) {
+        return this.#view.getUint32(at, true);
+    }
+}
+function readU16(buf, at) {
+    return buf[at] | (buf[at + 1] << 8);
+}
+function readU32(buf, at) {
+    return ((buf[at] |
+        (buf[at + 1] << 8) |
+        (buf[at + 2] << 16) |
+        (buf[at + 3] << 24)) >>>
+        0);
+}
+function decodeUtf16le(bytes) {
+    let s = '';
+    for (let i = 0; i + 1 < bytes.length; i += 2) {
+        s += String.fromCharCode(bytes[i] | (bytes[i + 1] << 8));
+    }
+    return s;
+}
+function concat(chunks) {
+    let total = 0;
+    for (const c of chunks)
+        total += c.length;
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const c of chunks) {
+        out.set(c, off);
+        off += c.length;
+    }
+    return out;
+}

package/dist/vba/codepage.d.ts

@@ -0,0 +1,18 @@
+export type Decoder = InstanceType<typeof TextDecoder>;
+/** Encodes text back to the project code page's MBCS bytes; throws on a character it cannot represent. */
+export type Encoder = (text: string) => Uint8Array;
+/**
+ * A `TextDecoder` for the given VBA project code page. Non-fatal (malformed bytes become U+FFFD rather
+ * than throwing) because recovered source is for reading, not re-encoding — a stray byte must not sink
+ * the whole extraction. An unknown code page falls back to windows-1252.
+ */
+export declare function decoderForCodePage(codePage: number): Decoder;
+/**
+ * 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 declare function encoderForCodePage(codePage: number): Encoder;