@shbernal/ts-xlsx 1.1.0 → 1.3.1

package/dist/io/xlsx/write-stream.js

@@ -1,29 +1,3 @@
-// The streaming `.xlsx` writer: author a workbook incrementally and emit its package through a Node
-// stream, rather than holding the finished bytes in one buffer as {@link writeXlsx} does.
-//
-// A producer adds worksheets, appends rows as it generates them, commits each sheet, then commits the
-// workbook — at which point the package is assembled and streamed out. The output goes to whichever
-// destination the caller chose at construction: its own pull-based `stream` to pipe, a caller-owned
-// `Writable` sink (an outbound upload), or a `filename` the writer opens. In every case `commit()`
-// settles — it resolves once a supplied sink has flushed the whole package and rejects if that sink
-// errors (an unopenable file), never hanging on a finish signal that will not come. The output rides a
-// genuinely
-// streamed zip container (fflate's `Zip`/`ZipDeflate`), which computes each entry's CRC-32
-// incrementally, so the archive is well-formed by construction — the defect the upstream "streaming
-// writer emits a corrupt zip" reports describe is structurally absent here. The bytes reload
-// identically to a whole-file write because both writers share `buildPackageParts` for every part.
-//
-// Peak memory: a row committed with `row.commit()` is serialised to its `<row>` XML immediately and
-// its cells evicted from the model, so an append-driven producer holds only the rows still in flight
-// rather than the whole sheet's cell graph. The eagerly-rendered rows intern into the workbook's live
-// style registry — the same one that emits `xl/styles.xml` — so their style ids stay correct; their
-// XML is handed to `buildPackageParts` and emitted at the head of `<sheetData>`. This eager path runs
-// with strings inline (a shared-strings pool is inherently whole-workbook, so it defeats bounding);
-// turning `useSharedStrings` on falls back to holding every row live until commit. A flushed row is a
-// finished row: it cannot join whole-sheet derivations, so a shared-formula clone in a committed row
-// is rejected, and rows reached only through `getCell` (never `row.commit()`) stay live and serialise
-// the ordinary way. The package bytes themselves are still assembled once at commit — a later slice
-// can flush each sheet's `<sheetData>` straight into its streamed zip entry to bound that half too.
 import { createWriteStream } from 'node:fs';
 import { PassThrough } from 'node:stream';
 import { Zip, ZipDeflate } from 'fflate';
@@ -32,13 +6,8 @@ import { INTERNAL } from '../../core/internal.js';
 import { isSharedFormulaValue } from '../../core/value.js';
 import { Workbook } from '../../core/workbook.js';
 import { AuthoringError } from '../../errors.js';
+import { FIXED_ENTRY_MTIME } from '../opc/zip-mtime.js';
 import { buildColumnDefaults, buildPackageParts, createStyleRegistry, Extent, renderRow, } from './write.js';
-/**
- * A row appended to a {@link WorksheetStreamWriter}. Style its cells through {@link cells}, then call
- * {@link commit} to mark it finished. In an eager (inline-strings) writer, committing serialises the
- * row and frees its cells from the model, bounding peak memory; with `useSharedStrings` on it is a
- * no-op and the row stays live until the workbook commits.
- */
 export class StreamedRow {
     #cells;
     #sheet;
@@ -49,12 +18,9 @@ export class StreamedRow {
         this.#sheet = sheet;
         this.#number = number;
     }
-    /** The cells this row materialised, for styling before it is committed. */
     get cells() {
         return this.#cells;
     }
-    /** Finalise the row: an eager writer serialises it now and releases its cells; otherwise a no-op.
-     * Committing twice is harmless — the second call does nothing rather than re-emitting the row. */
     commit() {
         if (this.#committed)
             return;
@@ -62,21 +28,12 @@ export class StreamedRow {
         this.#sheet?.flushRow(this.#number, this.#cells);
     }
 }
-/**
- * A worksheet being written incrementally. Append rows with {@link addRow}/{@link addRows}, style
- * cells through {@link getCell}, then {@link commit} to freeze it — after which any further mutation
- * is rejected with a legible error rather than silently accepted or crashing.
- */
 export class WorksheetStreamWriter {
     #sheet;
     #eager;
     #styles;
     #committed = false;
-    // The last row number this writer appended, tracked independently of the model: an eager writer
-    // evicts flushed rows, which lowers the model's used range, so leaning on it would reuse numbers.
     #lastRow = 0;
-    // The column defaults an eagerly-rendered row inherits, frozen at the first flush so every flushed
-    // row composes against the same columns even as later ones are defined.
     #columnDefaults;
     #flushedRows = [];
     #extent = new Extent();
@@ -86,16 +43,12 @@ export class WorksheetStreamWriter {
         this.#eager = eager;
         this.#styles = styles;
     }
-    /** The sheet's name. */
     get name() {
         return this.#sheet.name;
     }
-    /** The number of rows written so far — spans gaps and formatted-only rows, like the model, and
-     * survives the eviction of eagerly-flushed rows. */
     get rowCount() {
         return Math.max(this.#lastRow, this.#sheet.rowCount);
     }
-    /** Append one row of values after the last used row; the cells are returned for styling. */
     addRow(values) {
         this.#assertOpen();
         if (!this.#eager)
@@ -103,21 +56,16 @@ export class WorksheetStreamWriter {
         const number = this.#nextRowNumber();
         return new StreamedRow(this.#placeRow(number, values), this, number);
     }
-    /** Append a batch of rows in one call, each landing directly below the previous. */
     addRows(rows) {
         this.#assertOpen();
         if (!this.#eager)
             return this.#sheet.addRows(rows).map((cells) => new StreamedRow(cells, null, 0));
         return rows.map((values) => this.addRow(values));
     }
-    // The next append position: past both this writer's own high-water mark and any rows a `getCell`
-    // materialised, so appends never collide with random-access edits or with already-evicted rows.
     #nextRowNumber() {
         this.#lastRow = Math.max(this.#lastRow, this.#sheet.rowCount) + 1;
         return this.#lastRow;
     }
-    // Materialise a positional row at an explicit number (the model's own append would reuse numbers once
-    // eviction shrinks its used range), returning the cells for styling. A hole leaves its cell absent.
     #placeRow(number, values) {
         const cells = [];
         values.forEach((value, index) => {
@@ -127,14 +75,6 @@ export class WorksheetStreamWriter {
         });
         return cells;
     }
-    /**
-     * Serialise an eagerly-committed row and release its cells from the model. Called by
-     * {@link StreamedRow.commit}; the row's `<row>` XML is retained (interned into the workbook's live
-     * style registry so its ids stay valid) and the cell graph is dropped, bounding peak memory.
-     *
-     * @throws {AuthoringError} if the row carries a shared-formula cell — a finished row cannot join the
-     *   whole-sheet formula planning, so shared formulas must be authored through {@link getCell}.
-     */
     flushRow(number, cells) {
         for (const cell of cells) {
             if (isSharedFormulaValue(cell.value)) {
@@ -145,9 +85,6 @@ export class WorksheetStreamWriter {
         }
         this.#columnDefaults ??= buildColumnDefaults(this.#sheet);
         const properties = this.#sheet.getRow(number).properties;
-        // The row's outline depth is read off here because eviction is about to take its properties with
-        // it, and `<sheetFormatPr outlineLevelRow>` — written long after, once every row is flushed —
-        // reports the deepest level on the whole sheet.
         this.#maxRowOutlineLevel = Math.max(this.#maxRowOutlineLevel, properties?.outlineLevel ?? 0);
         const { xml, minCol, maxCol } = renderRow({ number, cells, properties }, {
             columnDefaults: this.#columnDefaults,
@@ -162,7 +99,6 @@ export class WorksheetStreamWriter {
         }
         this.#sheet[INTERNAL].evictRow(number);
     }
-    // The rows this writer flushed, or undefined if none — handed to buildPackageParts at commit.
     flushedSheet() {
         if (this.#flushedRows.length === 0)
             return undefined;
@@ -172,44 +108,22 @@ export class WorksheetStreamWriter {
             maxRowOutlineLevel: this.#maxRowOutlineLevel,
         };
     }
-    /** Address a cell by its A1 reference to read or style it before the sheet is committed. */
     getCell(reference) {
         this.#assertOpen();
         return this.#sheet.getCell(reference);
     }
-    /**
-     * Attach a data validation to a range before the sheet is committed. Delegates to the model, so the
-     * streamed package emits the `<dataValidations>` block in its CT_Worksheet position — before
-     * `<hyperlinks>` — because both writers share one worksheet serializer.
-     */
     addDataValidation(sqref, rule, options = {}) {
         this.#assertOpen();
         this.#sheet.addDataValidation(sqref, rule, options);
     }
-    /**
-     * Attach a conditional formatting to a range before the sheet is committed. Like every other block,
-     * it lands in its schema-mandated slot — after `<mergeCells>`, before `<dataValidations>` and
-     * `<hyperlinks>` — since the streamed sheet is serialized through the same path as a buffered write.
-     */
     addConditionalFormatting(formatting) {
         this.#assertOpen();
         this.#sheet.addConditionalFormatting(formatting);
     }
-    /**
-     * Anchor a workbook image (the id from {@link WorkbookStreamWriter.addImage}) to this sheet,
-     * spanning the rectangle from the top-left grid point `tl` to the bottom-right `br`. The streamed
-     * package emits the drawing part, its media relationship, and the sheet's `<drawing>` reference
-     * exactly as a buffered write does — both writers share `buildPackageParts`.
-     */
     addImage(imageId, anchor) {
         this.#assertOpen();
         this.#sheet.addImage(imageId, anchor);
     }
-    /**
-     * Apply the sheet's autofilter before it is committed; mirrors {@link Worksheet.autoFilter}. The
-     * streamed package emits `<autoFilter>` in its CT_Worksheet slot — after `<sheetProtection>` — and
-     * contributes the hidden `_FilterDatabase` defined name, exactly as a buffered write does.
-     */
     set autoFilter(filter) {
         this.#assertOpen();
         this.#sheet.autoFilter = filter;
@@ -217,24 +131,16 @@ export class WorksheetStreamWriter {
     get autoFilter() {
         return this.#sheet.autoFilter;
     }
-    /**
-     * Apply sheet-level protection before the sheet is committed; mirrors {@link Worksheet.protect}. The
-     * shared serializer places `<sheetProtection>` ahead of `<autoFilter>` per CT_Worksheet, so a
-     * streamed sheet carrying both stays valid rather than corrupt.
-     */
     protect(password, options = {}) {
         this.#assertOpen();
         this.#sheet.protect(password, options);
     }
-    /** Freeze the sheet: no more rows or edits may be added after this. */
     commit() {
         this.#committed = true;
     }
-    /** Whether the sheet has been committed. */
     get committed() {
         return this.#committed;
     }
-    // Internal: the underlying model sheet, so the workbook writer can serialise it at commit time.
     get model() {
         return this.#sheet;
     }
@@ -244,26 +150,15 @@ export class WorksheetStreamWriter {
         }
     }
 }
-/**
- * A workbook written incrementally to a Node stream. Add worksheets, append their rows, commit each
- * sheet, then {@link commit} the workbook to assemble and stream the package. The produced bytes are
- * available both as the resolved value of `commit()` and through {@link stream} (a Node `Readable`
- * that a caller can `pipe`).
- */
 export class WorkbookStreamWriter {
     #workbook = new Workbook();
     #sheets = [];
     #writeOptions;
     #sink;
-    // The single style registry shared by the eager per-row flush and the commit-time serialisation, so a
-    // flushed row's style ids match the styles.xml built from the same table.
     #styles;
-    // Eager per-row flushing runs with strings inline; a shared-strings pool is inherently whole-workbook,
-    // so it cannot bound memory — turning it on keeps every row live until commit.
     #eager;
     #stream;
     #committed = false;
-    /** Calculation settings for the workbook; set `fullCalcOnLoad` before committing to emit it. */
     calcProperties = {};
     constructor(options = {}) {
         this.#writeOptions = { useSharedStrings: options.useSharedStrings ?? false };
@@ -275,32 +170,19 @@ export class WorkbookStreamWriter {
         this.#sink =
             options.stream ?? (options.filename ? createWriteStream(options.filename) : undefined);
     }
-    /** Document-level metadata written to the package's core properties. */
     get properties() {
         return this.#workbook.properties;
     }
-    /**
-     * The output stream carrying the package bytes. A caller drives it with Node's standard idiom —
-     * `writer.stream.pipe(out)` — which composes because `pipe` returns its destination. The stream is
-     * created lazily on first access so a caller handing the writer its own sink is still free to
-     * ignore this one.
-     */
     get stream() {
         this.#stream ??= new PassThrough();
         return this.#stream;
     }
-    /**
-     * Register a picture's bytes on the workbook's shared media registry and return its id, to anchor
-     * on any sheet with {@link WorksheetStreamWriter.addImage}. Mirrors {@link Workbook.addImage}: one
-     * media part backs an image anchored on several sheets. Rejected once the workbook is committed.
-     */
     addImage(options) {
         if (this.#committed) {
             throw new AuthoringError('the workbook is already committed — no more images can be registered');
         }
         return this.#workbook.addImage(options);
     }
-    /** Create a worksheet and append it to the workbook. */
     addWorksheet(name, options = {}) {
         if (this.#committed) {
             throw new AuthoringError('the workbook is already committed — no more worksheets can be added');
@@ -309,11 +191,6 @@ export class WorkbookStreamWriter {
         this.#sheets.push(sheet);
         return sheet;
     }
-    /**
-     * Assemble the workbook into its package, stream the bytes through {@link stream}, and resolve with
-     * the same bytes. Every sheet is frozen first, so a row added after this rejects legibly. Idempotent
-     * only in that a second call throws rather than re-emitting.
-     */
     async commit() {
         if (this.#committed) {
             throw new AuthoringError('the workbook is already committed');
@@ -323,9 +200,6 @@ export class WorkbookStreamWriter {
             sheet.commit();
         if (this.calcProperties.fullCalcOnLoad)
             this.#workbook.fullCalcOnLoad = true;
-        // Hand every sheet's eagerly-flushed rows to the shared serialiser, which emits them alongside the
-        // rows still live in the model. The style registry is the same one the flushed rows interned into,
-        // so styles.xml stays consistent with the ids already baked into their XML.
         const flushed = new Map();
         for (const sheet of this.#sheets) {
             const sheetFlushed = sheet.flushedSheet();
@@ -339,9 +213,6 @@ export class WorkbookStreamWriter {
         });
         const owned = this.#stream;
         const sink = this.#sink;
-        // Track the caller sink's terminal state before writing a byte, so an open failure that errors on a
-        // later tick (a bad filename) is caught rather than lost — the whole point of the reject-not-hang
-        // contract.
         const sinkSettled = sink ? settleOnFinish(sink) : undefined;
         const bytes = await streamZipPackage(parts, (chunk) => {
             owned?.write(chunk);
@@ -353,19 +224,12 @@ export class WorkbookStreamWriter {
         return bytes;
     }
 }
-// Resolve when a caller-supplied sink has flushed the whole package (`finish`), or reject if it errors
-// (`error`) — the commit promise must settle either way, never hang. Whichever fires first wins; the
-// other is ignored.
 function settleOnFinish(sink) {
     return new Promise((resolve, reject) => {
         sink.once('finish', resolve);
         sink.once('error', reject);
     });
 }
-// Zip the package parts through fflate's streaming container, forwarding each output chunk to `onChunk`
-// as it is produced and resolving with the whole archive once the final chunk arrives. `ZipDeflate`
-// deflates synchronously, so the callback fires inline as each part is pushed — the CRC-32 fflate
-// stamps into every entry's header therefore always matches the bytes it just compressed.
 function streamZipPackage(parts, onChunk) {
     return new Promise((resolve, reject) => {
         const collected = [];
@@ -381,6 +245,7 @@ function streamZipPackage(parts, onChunk) {
         });
         for (const [name, data] of Object.entries(parts)) {
             const entry = new ZipDeflate(name, { level: 6 });
+            entry.mtime = FIXED_ENTRY_MTIME;
             zip.add(entry);
             entry.push(data, true);
         }

package/dist/io/xlsx/write.d.ts

@@ -37,6 +37,10 @@ export interface InternalWriteOptions extends WriteOptions {
 /**
  * Serialise a workbook into an `.xlsx` package.
  *
+ * The bytes are a pure function of the workbook: an unchanged model written twice produces two
+ * identical archives, because entry timestamps are pinned to a fixed date rather than taken from the
+ * clock. A committed `.xlsx` therefore only changes when something about it changed.
+ *
  * @throws {AuthoringError} if the workbook has no worksheets (a zero-sheet package is corrupt),
  *   or holds a value the writer cannot yet represent.
  */
@@ -44,7 +48,7 @@ export declare function writeXlsx(workbook: Workbook, options?: WriteOptions): U
 /**
  * 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
+ * Produces the same package {@link writeXlsx} does — byte for byte, entry timestamps included — 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

package/dist/io/xlsx/write.js

@@ -1,23 +1,9 @@
-// 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 { FIXED_ENTRY_MTIME } from '../opc/zip-mtime.js';
 import { collectComments, commentsXml, vmlDrawingXml } from './comments.js';
 import { collectHyperlinks, planHyperlinks } from './hyperlinks.js';
 import { drawingRelsXml, drawingXml } from './images.js';
@@ -31,39 +17,13 @@ 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 {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 });
+    return zipSync(buildPackageParts(workbook, options), { level: 6, mtime: FIXED_ENTRY_MTIME });
 }
-/**
- * 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 {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) => {
+        zip(parts, { level: 6, mtime: FIXED_ENTRY_MTIME }, (error, data) => {
             if (error)
                 reject(error);
             else
@@ -71,47 +31,22 @@ export async function writeXlsxAsync(workbook, options = {}) {
         });
     });
 }
-/**
- * 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;
@@ -128,39 +63,15 @@ function resolveSheetReferences(plan) {
         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 {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;
@@ -177,8 +88,6 @@ export function buildPackageParts(workbook, options = {}) {
                 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,
@@ -186,12 +95,6 @@ export function buildPackageParts(workbook, options = {}) {
             });
             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
@@ -221,8 +124,6 @@ export function buildPackageParts(workbook, options = {}) {
         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 {
@@ -239,22 +140,11 @@ export function buildPackageParts(workbook, options = {}) {
     });
     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));
+        return worksheetXml(sheet, plan.tables, styles, resolveSheetReferences(plan), plan.hyperlinks, sharedStrings, 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)
@@ -272,14 +162,7 @@ export function buildPackageParts(workbook, options = {}) {
         .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);
@@ -287,8 +170,6 @@ export function buildPackageParts(workbook, options = {}) {
         ...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}`;
@@ -297,22 +178,17 @@ export function buildPackageParts(workbook, options = {}) {
         '[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()),
+        'docProps/app.xml': strToU8(appPropsXml(workbook.properties)),
         '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) {
@@ -326,9 +202,6 @@ export function buildPackageParts(workbook, options = {}) {
     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;
@@ -363,9 +236,6 @@ function emitSheetParts(files, perSheet, sheetXml) {
         }
     });
 }
-// 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;
@@ -384,8 +254,6 @@ function emitPivotParts(files, allPivots) {
         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;

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

@@ -1,12 +1,4 @@
 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>`;
 }