@shbernal/ts-xlsx 1.0.0

package/dist/io/xlsx/write.js

@@ -0,0 +1,396 @@
+// The buffered `.xlsx` writer: a Workbook model in, an OPC zip package out.
+//
+// It serialises the part of the model that exists today — worksheets; cells holding a
+// number, string, boolean, or formula; column/row formatting; page margins and
+// header/footer; merged ranges; and worksheet tables — into a valid package (content
+// types, relationships, workbook, per-sheet XML, table parts, the default theme and
+// stylesheet, and core/app properties). Styles, images, and the richer value kinds land
+// as the model grows; until then the writer refuses a value it cannot represent
+// faithfully rather than emitting a lossy or corrupt package.
+//
+// This module is the orchestrator: it plans the package graph (via `package-plan.ts`) and
+// stitches the serialised parts (from `workbook-xml.ts` and `worksheet-xml.ts`) into the
+// part map. The row/cell renderer and the sheet's public render types live in
+// `worksheet-xml.ts` and are re-exported here so the streaming writer's import surface is
+// unchanged.
+import { strToU8, zip, zipSync } from 'fflate';
+import { DEFAULT_THEME_XML } from "../../core/theme.js";
+import { AuthoringError } from "../../errors.js";
+import { THEME_PART_PATH } from "../opc/part-paths.js";
+import { relsPartXml } from "../opc/rels.js";
+import { collectComments, commentsXml, vmlDrawingXml } from "./comments.js";
+import { collectHyperlinks, planHyperlinks } from "./hyperlinks.js";
+import { drawingRelsXml, drawingXml } from "./images.js";
+import { planMedia, planPreservedParts, SheetRelIds, } from "./package-plan.js";
+import { pivotCacheDefinitionXml, pivotCacheRecordsXml, pivotTableXml } from "./pivot.js";
+import { REL } from "./relationships.js";
+import { SharedStringTable } from "./shared-strings.js";
+import { StyleRegistry } from "./styles.js";
+import { tableXml } from "./tables.js";
+import { personsXml, threadedCommentsXml } from "./threaded-comments.js";
+import { appPropsXml, contentTypesXml, corePropsXml, FIXED_WORKBOOK_REL_COUNT, rootRelsXml, workbookRelsXml, workbookXml, } from "./workbook-xml.js";
+import { worksheetRelsXml, worksheetXml, } from "./worksheet-xml.js";
+export { buildColumnDefaults, Extent, renderRow, } from "./worksheet-xml.js";
+/**
+ * Serialise a workbook into an `.xlsx` package.
+ *
+ * @throws {@link AuthoringError} if the workbook has no worksheets (a zero-sheet package is corrupt),
+ *   or holds a value the writer cannot yet represent.
+ */
+export function writeXlsx(workbook, options = {}) {
+    return zipSync(buildPackageParts(workbook, options), { level: 6 });
+}
+/**
+ * Serialise a workbook into an `.xlsx` package, deflating off the calling thread.
+ *
+ * Produces the same package {@link writeXlsx} does — every part compresses to identical bytes — and
+ * exists for one reason: DEFLATE dominates the cost of writing a large workbook, and {@link writeXlsx}
+ * spends all of it on the caller's thread. Here `fflate` deflates each part in a worker, so the event
+ * loop keeps turning (stalls drop from the whole write to tens of milliseconds) and parts compress in
+ * parallel, which on a multi-sheet workbook also finishes sooner. On a single-sheet workbook there is
+ * only one part to deflate, so expect responsiveness rather than speed.
+ *
+ * Building the parts still happens on the calling thread — only compression moves. That is why there
+ * is no `readXlsxAsync` mirroring this: reading is dominated by XML parsing and model building, which
+ * no worker can take, and the reader's zip-bomb ceiling is enforced by counting output between
+ * synchronous input slices. See ADR-0024.
+ *
+ * @throws {@link AuthoringError} — as a rejection — under the same conditions as {@link writeXlsx};
+ *   the part-building it shares happens before any worker is involved. A failure raised by the zip
+ *   layer itself (including an environment that cannot spawn a worker) propagates unwrapped, exactly
+ *   as it does from {@link writeXlsx}.
+ */
+export async function writeXlsxAsync(workbook, options = {}) {
+    const parts = buildPackageParts(workbook, options);
+    return await new Promise((resolve, reject) => {
+        zip(parts, { level: 6 }, (error, data) => {
+            if (error)
+                reject(error);
+            else
+                resolve(data);
+        });
+    });
+}
+/**
+ * A style registry seeded from a workbook's read-in style layers (differential styles, named cell
+ * styles, custom indexed palette), ready to intern authored styles after them. Both the buffered
+ * pass and the streaming writer build their registry through here so a cell's style id means the
+ * same thing whichever writer emits it.
+ */
+export function createStyleRegistry(workbook) {
+    // Font id 0 is the workbook's own default face, resolved from what it declared, what was authored,
+    // and its theme's body typeface — never an assumed Calibri, which would re-face every empty cell
+    // and change the metric every character-unit column width is expressed in.
+    const styles = new StyleRegistry({
+        defaultFont: workbook.defaultFont,
+        ...(workbook.declaredDefaultFont === undefined
+            ? {}
+            : { declaredDefaultFont: workbook.declaredDefaultFont }),
+    });
+    // Seed the differential-style table with the fragments read from a source file so conditional
+    // formatting's dxfId references stay valid; styles authored on rules append after them.
+    styles.seedDifferentialStyles(workbook.differentialStyles);
+    // Seed the named cell-style layer (cellStyleXfs/cellStyles) so each style's facets re-intern into the
+    // rebuilt sub-tables and a cell's xfId link stays valid; without any, the default Normal alone emits.
+    styles.seedNamedStyles(workbook.namedStyles);
+    // Seed the custom indexed-color palette so it re-emits verbatim and an `indexed="…"` colour keeps
+    // its intended RGB; a workbook that never overrode the palette seeds nothing and writes no <colors>.
+    styles.seedIndexedColors(workbook.indexedColors);
+    // Seed the author's "Recent Colors" swatches so they re-emit unchanged rather than being reset.
+    styles.seedMruColors(workbook.mruColors);
+    // Seed the custom table-style definitions so a table's `styleName` still names a real definition and
+    // each element's dxfId still indexes the differential-style table seeded above at its original index.
+    styles.seedTableStyles(workbook.tableStyles);
+    // Authored styles append after the preserved ones, and intern their elements' formatting after the
+    // seeded dxfs — the ordering that keeps every preserved dxfId pointing where it did.
+    for (const style of workbook.customTableStyles)
+        styles.addTableStyle(style);
+    return styles;
+}
+// Resolve one sheet's tail reference ids (the `<drawing>`/`<legacyDrawing>`/`<legacyDrawingHF>`/
+// `<picture>` slots and the slicer list) from its plan. A preserved `<drawing>` and a modeled one are
+// mutually exclusive, so the drawing slot takes whichever exists; a comment's VML rides the legacy-
+// drawing slot; and each preserved slicer surfaces its rel id so the `<x14:slicerList>` can reactivate
+// the widget rather than orphan its part.
+function resolveSheetReferences(plan) {
+    const refs = plan.preservedRefs;
+    const preservedDrawingRelId = refs.find((ref) => ref.element === 'drawing')?.relId ?? null;
+    const legacyDrawingHFRelId = refs.find((ref) => ref.element === 'legacyDrawingHF')?.relId ?? null;
+    const slicerRelIds = refs
+        .filter((ref) => ref.relType.endsWith('/slicer'))
+        .map((ref) => ref.relId);
+    return {
+        drawingRelId: plan.drawing?.relId ?? preservedDrawingRelId,
+        legacyDrawingRelId: plan.comments?.vmlRelId ?? null,
+        printerSettingsRelId: plan.printerSettings?.relId ?? null,
+        backgroundRelId: plan.background?.relId ?? null,
+        legacyDrawingHFRelId,
+        slicerRelIds,
+    };
+}
+/**
+ * Assemble a workbook into the map of OPC package parts (part name → bytes) that make up an `.xlsx`,
+ * short of zipping them. This is the whole serialisation — content types, relationships, workbook,
+ * per-sheet XML, styles, theme, media, tables, and props — factored out of {@link writeXlsx} so the
+ * streaming writer can drive the identical parts through a streamed zip container rather than
+ * `zipSync`. Neither writer duplicates a byte of serialisation.
+ *
+ * @throws {@link AuthoringError} if the workbook has no worksheets, or holds a value the writer cannot represent.
+ */
+export function buildPackageParts(workbook, options = {}) {
+    const sheets = workbook.worksheets;
+    if (sheets.length === 0) {
+        throw new AuthoringError('cannot write a workbook with no worksheets — a zero-sheet package is corrupt to Excel');
+    }
+    // With the option on, plain string cell values are pooled into a shared-strings table interned
+    // during the sheet pass (like the style registry); a null table keeps every string inline.
+    const sharedStrings = options.useSharedStrings ? new SharedStringTable() : null;
+    // Anchored images share workbook-wide media: every image a sheet references becomes one media part,
+    // addressed by a global number. Resolved before the sheet loop so a drawing's embeds can target it.
+    const media = planMedia(workbook, sheets);
+    // Content the model does not interpret — a vector-shape drawing, a header/footer image, a pivot
+    // table and its caches, a slicer — captured on read and re-emitted verbatim onto collision-proof
+    // paths. Preserved parts are renumbered past the parts the writer generates of the same kind
+    // (drawings, VML, media), so resolving them needs only those generated counts; each sheet's
+    // preserved references take their sheet-local rel ids in canonical position in the loop below.
+    const generatedDrawingCount = sheets.filter((sheet) => sheet.images.length > 0).length;
+    const preserved = planPreservedParts(workbook, generatedDrawingCount, media.parts.length);
+    // Plan every sheet's parts in a single pass, drawing each sheet-local relationship id from that
+    // sheet's allocator in canonical order: tables, drawing, comments (VML + comments part), printer
+    // settings, external hyperlinks, background, preserved references, pivot tables. One running
+    // allocator per sheet is what keeps the ids gapless and collision-free — no step re-derives its
+    // offset by summing the ones before it, so none can drift into another's id. Part numbers (tables,
+    // drawings, pivots) are global across the workbook and counted here in the same pass.
+    let tableNumber = 0;
+    let drawingNumber = 0;
+    let pivotNumber = 0;
+    const perSheet = sheets.map((sheet, i) => {
+        const rels = new SheetRelIds();
+        const tables = sheet.tables.map((table) => ({
+            table,
+            number: ++tableNumber,
+            relId: rels.next(),
+        }));
+        let drawing = null;
+        if (sheet.images.length > 0) {
+            const images = sheet.images.map((image, j) => {
+                const registered = workbook.getImage(image.imageId);
+                return {
+                    anchor: image.anchor,
+                    // The embed id is local to the drawing part's own rels, not the sheet's, so it is numbered
+                    // per image from rId1 rather than drawn from the sheet allocator.
+                    embedId: `rId${j + 1}`,
+                    mediaNumber: media.numberById.get(image.imageId),
+                    extension: registered.extension,
+                };
+            });
+            drawing = { number: ++drawingNumber, relId: rels.next(), images };
+        }
+        // A conversation and the legacy fallback `<comment>` that binds its cell to it are two halves of one
+        // representation, so both are derived from this single list and neither can be emitted without the
+        // other. Verified against desktop Excel: a `tc=` fallback whose thread part is absent shows as neither
+        // a thread nor a note — the text disappears rather than degrading — and a thread part whose fallback is
+        // absent is ignored, leaving the cell blank. A thread with no messages is not one of them: it has
+        // nothing to say, and no head id for its replies or its fallback to hang off.
+        const threads = sheet.commentThreads.filter((thread) => thread.comments.length > 0);
+        const sheetComments = collectComments(sheet, threads);
+        const comments = sheetComments.length === 0
+            ? null
+            : {
+                number: i + 1,
+                comments: sheetComments,
+                vmlRelId: rels.next(),
+                commentsRelId: rels.next(),
+            };
+        const threadedComments = threads.length === 0 ? null : { number: i + 1, threads, relId: rels.next() };
+        const printerData = sheet.pageSetup.printerSettings;
+        const printerSettings = printerData === undefined ? null : { number: i + 1, data: printerData, relId: rels.next() };
+        const hyperlinks = planHyperlinks(collectHyperlinks(sheet), rels);
+        let background = null;
+        if (sheet.backgroundImageId !== undefined) {
+            const registered = workbook.getImage(sheet.backgroundImageId);
+            if (registered === undefined) {
+                throw new AuthoringError(`sheet "${sheet.name}" sets background image id ${sheet.backgroundImageId}, which is not registered on the workbook`);
+            }
+            background = {
+                relId: rels.next(),
+                mediaNumber: media.numberById.get(sheet.backgroundImageId),
+                extension: registered.extension,
+            };
+        }
+        const preservedRefs = (preserved.perSheet[i] ?? []).map((reference) => ({ ...reference, relId: rels.next() }));
+        const pivots = sheet.pivotTables.map((table) => {
+            const number = ++pivotNumber;
+            // Each pivot is numbered globally (its parts and its `cacheId` must be workbook-unique); the
+            // workbook relationship reaching its cache is assigned once the modeled workbook rels are known.
+            return { number, cacheId: String(number), table, sheetRelId: rels.next(), workbookRelId: '' };
+        });
+        return {
+            tables,
+            drawing,
+            comments,
+            threadedComments,
+            printerSettings,
+            hyperlinks,
+            background,
+            preservedRefs,
+            pivots,
+        };
+    });
+    const allTables = perSheet.flatMap((plan) => plan.tables);
+    const allPivots = perSheet.flatMap((plan) => plan.pivots);
+    // Serialise the worksheets first: interning each cell/row fill into the style table is a
+    // side effect of that pass, so styles.xml can only be generated once every sheet is done. The
+    // streaming writer supplies its own registry (already seeded, and already carrying its eagerly
+    // flushed rows' styles); the buffered path seeds a fresh one here.
+    const styles = options.styles ?? createStyleRegistry(workbook);
+    const sheetXml = sheets.map((sheet, i) => {
+        const plan = perSheet[i];
+        return worksheetXml(sheet, plan.tables, styles, resolveSheetReferences(plan), plan.hyperlinks, sharedStrings, 
+        // Exactly one sheet is marked selected; the model resolves which, so no package can ship with
+        // none selected (no view initialised on open) or with several (an accidental group selection,
+        // where an edit to one sheet lands on all of them).
+        i === workbook.activeTabIndex, options.flushed?.get(sheet));
+    });
+    // The pool is filled only once every sheet is serialised. Emit the part (and its rel + content
+    // type) solely when the option is on and at least one string was interned, so a workbook with no
+    // string cells never fabricates an empty table.
+    const hasSharedStrings = sharedStrings !== null && !sharedStrings.isEmpty;
+    const commentNumbers = perSheet
+        .map((plan) => plan.comments)
+        .filter((c) => c !== null)
+        .map((c) => c.number);
+    const drawingNumbers = perSheet
+        .map((plan) => plan.drawing)
+        .filter((d) => d !== null)
+        .map((d) => d.number);
+    const printerSettingsNumbers = perSheet
+        .map((plan) => plan.printerSettings)
+        .filter((p) => p !== null)
+        .map((p) => p.number);
+    const threadedCommentNumbers = perSheet
+        .map((plan) => plan.threadedComments)
+        .filter((t) => t !== null)
+        .map((t) => t.number);
+    // The identity registry is emitted only beside the thread parts that point into it. With no conversation
+    // in the package nothing can reference a `<person>`, so the part would be a workbook-level relationship
+    // to dead weight — and it is the messages, not the registry, that make an identity worth carrying.
+    const persons = threadedCommentNumbers.length === 0 ? [] : workbook.persons;
+    // A preserved workbook reference's relationship id follows the modeled workbook rels — the sheets,
+    // styles, theme, and (when emitted) shared strings and the threaded-comment person registry — so adding
+    // one never renumbers an id already used. The workbook body and its rels part are wired from the same
+    // assignment, so a pivot cache's `<pivotCaches>` registration and its relationship agree on the id.
+    const modeledWorkbookRelCount = sheets.length + FIXED_WORKBOOK_REL_COUNT + (hasSharedStrings ? 1 : 0);
+    const personsRelId = persons.length === 0 ? null : `rId${modeledWorkbookRelCount + 1}`;
+    const workbookRelBase = modeledWorkbookRelCount + (personsRelId === null ? 0 : 1);
+    const preservedWorkbookRels = preserved.workbook.map((ref, i) => ({
+        ...ref,
+        relId: `rId${workbookRelBase + 1 + i}`,
+    }));
+    // A generated pivot cache's workbook relationship follows the preserved ones; the assignment
+    // mutates the shared plan so the `<pivotCaches>` body and the rels part read the same id.
+    const pivotWorkbookRelBase = workbookRelBase + preserved.workbook.length;
+    allPivots.forEach((pivot, i) => {
+        pivot.workbookRelId = `rId${pivotWorkbookRelBase + 1 + i}`;
+    });
+    const files = {
+        '[Content_Types].xml': strToU8(contentTypesXml(sheets.length, allTables, commentNumbers, drawingNumbers, printerSettingsNumbers, media.extensions, hasSharedStrings, preserved.parts, allPivots, preservedWorkbookRels, threadedCommentNumbers, persons.length > 0)),
+        '_rels/.rels': strToU8(rootRelsXml(preserved.root)),
+        'docProps/core.xml': strToU8(corePropsXml(workbook.properties)),
+        'docProps/app.xml': strToU8(appPropsXml()),
+        'xl/workbook.xml': strToU8(workbookXml(workbook, preservedWorkbookRels, allPivots)),
+        'xl/_rels/workbook.xml.rels': strToU8(workbookRelsXml(sheets.length, hasSharedStrings, personsRelId, preservedWorkbookRels, allPivots)),
+        'xl/styles.xml': strToU8(styles.toXml()),
+    };
+    // A theme read from a source package is emitted through the preserved-part path, closure and all —
+    // with any authored overrides already spliced into its entry part by the planner. A workbook without
+    // one gets its authored theme, or the library's default, which the stylesheet's `theme="1"` default
+    // font still needs something to resolve against.
+    if (!preserved.themeEmitted) {
+        files[THEME_PART_PATH] = strToU8(workbook.authoredThemeXml() ?? DEFAULT_THEME_XML);
+    }
+    if (hasSharedStrings) {
+        files['xl/sharedStrings.xml'] = strToU8(sharedStrings.toXml());
+    }
+    // Singular and unnumbered, unlike the per-sheet thread parts: one registry serves the whole workbook.
+    if (persons.length > 0)
+        files['xl/persons/person.xml'] = strToU8(personsXml(persons));
+    for (const part of media.parts) {
+        files[`xl/media/image${part.number}.${part.extension}`] = part.data;
+    }
+    emitSheetParts(files, perSheet, sheetXml);
+    for (const { table, number } of allTables) {
+        files[`xl/tables/table${number}.xml`] = strToU8(tableXml(table, number));
+    }
+    emitPivotParts(files, allPivots);
+    emitPreservedParts(files, preserved.parts);
+    return files;
+}
+// Emit each sheet's own parts: the sheet XML, its rels part (only when the sheet references something),
+// and the drawing/comment/printer-settings parts those relationships point at. `sheetXml[i]` is the
+// already-serialised body for `perSheet[i]`, indexed in lockstep.
+function emitSheetParts(files, perSheet, sheetXml) {
+    perSheet.forEach((plan, i) => {
+        const { tables, drawing, comments, threadedComments, printerSettings, background, hyperlinks, preservedRefs, pivots, } = plan;
+        const hasExternalHyperlink = hyperlinks.some((link) => link.relId !== undefined);
+        files[`xl/worksheets/sheet${i + 1}.xml`] = strToU8(sheetXml[i]);
+        if (tables.length > 0 ||
+            drawing !== null ||
+            comments !== null ||
+            threadedComments !== null ||
+            printerSettings !== null ||
+            background !== null ||
+            hasExternalHyperlink ||
+            preservedRefs.length > 0 ||
+            pivots.length > 0) {
+            files[`xl/worksheets/_rels/sheet${i + 1}.xml.rels`] = strToU8(worksheetRelsXml(tables, drawing, comments, threadedComments, printerSettings, background, hyperlinks, preservedRefs, pivots));
+        }
+        if (printerSettings !== null) {
+            files[`xl/printerSettings/printerSettings${printerSettings.number}.bin`] =
+                printerSettings.data;
+        }
+        if (drawing !== null) {
+            files[`xl/drawings/drawing${drawing.number}.xml`] = strToU8(drawingXml(drawing.images));
+            const targets = drawing.images.map((image) => `../media/image${image.mediaNumber}.${image.extension}`);
+            files[`xl/drawings/_rels/drawing${drawing.number}.xml.rels`] = strToU8(drawingRelsXml(targets));
+        }
+        if (comments !== null) {
+            files[`xl/comments${comments.number}.xml`] = strToU8(commentsXml(comments.comments));
+            files[`xl/drawings/vmlDrawing${comments.number}.vml`] = strToU8(vmlDrawingXml(comments.comments));
+        }
+        if (threadedComments !== null) {
+            files[`xl/threadedComments/threadedComment${threadedComments.number}.xml`] = strToU8(threadedCommentsXml(threadedComments.threads));
+        }
+    });
+}
+// Emit every pivot table's three chained parts. A pivot spans a pivot-table part (linked from its host
+// sheet) that references a cache definition, which references its cache records. Each cache carries a
+// rels part naming the next link by `rId1` — the id the definition/table XML resolves against.
+function emitPivotParts(files, allPivots) {
+    for (const pivot of allPivots) {
+        const { number, cacheId, table } = pivot;
+        files[`xl/pivotTables/pivotTable${number}.xml`] = strToU8(pivotTableXml(table, `PivotTable${number}`, cacheId));
+        files[`xl/pivotTables/_rels/pivotTable${number}.xml.rels`] = strToU8(relsPartXml([
+            {
+                id: 'rId1',
+                type: REL.pivotCacheDefinition,
+                target: `../pivotCache/pivotCacheDefinition${number}.xml`,
+            },
+        ]));
+        files[`xl/pivotCache/pivotCacheDefinition${number}.xml`] = strToU8(pivotCacheDefinitionXml(table));
+        files[`xl/pivotCache/_rels/pivotCacheDefinition${number}.xml.rels`] = strToU8(relsPartXml([
+            { id: 'rId1', type: REL.pivotCacheRecords, target: `pivotCacheRecords${number}.xml` },
+        ]));
+        files[`xl/pivotCache/pivotCacheRecords${number}.xml`] = strToU8(pivotCacheRecordsXml(table));
+    }
+}
+// Emit the verbatim-preserved parts (and their rewired rels) last: their paths are collision-proof, so
+// ordering against the generated parts does not matter.
+function emitPreservedParts(files, parts) {
+    for (const part of parts) {
+        files[part.path] = part.bytes;
+        if (part.relsPath !== null && part.relsXml !== null) {
+            files[part.relsPath] = strToU8(part.relsXml);
+        }
+    }
+}

package/dist/io/xlsx/x14-ext.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Wrap an x14 extension body in the `<ext>` envelope every worksheet- and workbook-level x14
+ * extension shares: a `uri` scoping the extension to its feature (a fixed GUID from
+ * {@link namespaces.ts}) plus the `xmlns:x14` binding the extension namespace on the element itself —
+ * Excel declares it per `<ext>`, never at the part root. Callers needing an `<extLst>` wrapper add it
+ * around the result; the producers the worksheet serialiser gathers return this bare so several exts
+ * compose under a single shared `<extLst>`.
+ */
+export declare function x14Ext(uri: string, body: string): string;

package/dist/io/xlsx/x14-ext.js

@@ -0,0 +1,12 @@
+import { X14_NS } from "./namespaces.js";
+/**
+ * Wrap an x14 extension body in the `<ext>` envelope every worksheet- and workbook-level x14
+ * extension shares: a `uri` scoping the extension to its feature (a fixed GUID from
+ * {@link namespaces.ts}) plus the `xmlns:x14` binding the extension namespace on the element itself —
+ * Excel declares it per `<ext>`, never at the part root. Callers needing an `<extLst>` wrapper add it
+ * around the result; the producers the worksheet serialiser gathers return this bare so several exts
+ * compose under a single shared `<extLst>`.
+ */
+export function x14Ext(uri, body) {
+    return `<ext uri="${uri}" xmlns:x14="${X14_NS}">${body}</ext>`;
+}

package/dist/vba/cfb-writer.d.ts

@@ -0,0 +1,19 @@
+export interface CfbStream {
+    /** The exact directory-entry name. At most 31 UTF-16 code units ([MS-CFB] name limit). */
+    readonly name: string;
+    readonly data: Uint8Array;
+}
+export interface CfbStorage {
+    readonly name: string;
+    readonly children: readonly CfbNode[];
+}
+export type CfbNode = CfbStream | CfbStorage;
+/**
+ * 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 declare function writeCompoundFile(root: readonly CfbNode[]): Uint8Array;