@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/dist/io/xlsx/tables.js

@@ -1,11 +1,3 @@
-// Worksheet tables (OOXML `<table>` parts, `xl/tables/table{n}.xml`) — both directions. The writer
-// (`tableXml`) turns a `Table` into its part; the reader (`parseTable`) is its inverse, turning a
-// stored part back into the `TableOptions` a worksheet re-registers.
-//
-// The part stores the table's *full* occupied range (`ref="A1:B3"`), whereas the model anchors at a
-// single top-left cell plus a data-row count. The two are equivalent: the data-row count is the
-// range height minus the header row (present unless `headerRowCount="0"`) and the totals row (present
-// only when `totalsRowCount` is positive), so reconstructing one from the other is lossless.
 import { decodeRange, encodeAddress } from '../../core/address.js';
 import { isTotalsRowFunction, } from '../../core/table.js';
 import { boolAttr, escapeAttr, escapeText, XML_DECLARATION } from '../../xml/xml.js';
@@ -14,12 +6,7 @@ import { NS } from './relationships.js';
 export function tableXml(table, id) {
     const name = escapeAttr(table.name);
     const displayName = escapeAttr(table.displayName);
-    // headerRowCount defaults to 1 in OOXML, so only a headerless table needs it stated.
     const headerRowCount = table.headerRow ? '' : ' headerRowCount="0"';
-    // A present totals row implies it is shown, so it only needs the count. Without a totals row the
-    // model's tri-state totalsRowShown decides: emit the flag Excel recorded, or nothing when the
-    // source omitted it — injecting `totalsRowShown="0"` onto a table that lacked the attribute is
-    // exactly the spurious change that makes Excel treat an otherwise-valid table as corrupt.
     let totals;
     if (table.totalsRow) {
         totals = ' totalsRowCount="1"';
@@ -40,12 +27,8 @@ export function tableXml(table, id) {
         tableStyleInfoXml(table.style) +
         '</table>');
 }
-// Excel's default table appearance, written for a table that carries no style of its own.
 const DEFAULT_TABLE_STYLE = '<tableStyleInfo name="TableStyleMedium2" showFirstColumn="0" showLastColumn="0" ' +
     'showRowStripes="1" showColumnStripes="0"/>';
-// Emit `<tableStyleInfo>` from the model's style, or the default when none was captured. Each
-// attribute is written only when the model holds it, so a style read without (say) a `name` — or a
-// part that omitted a banding flag — re-emits exactly as it arrived rather than gaining an attribute.
 function tableStyleInfoXml(style) {
     if (style === undefined)
         return DEFAULT_TABLE_STYLE;
@@ -67,46 +50,30 @@ function tableColumnXml(column, id) {
     if (column.totalsRowFunction !== undefined) {
         attrs += ` totalsRowFunction="${escapeAttr(column.totalsRowFunction)}"`;
     }
-    // A `custom` total is carried by a `<totalsRowFormula>` child rather than a built-in function, so
-    // the element is non-self-closing when one is present. The formula is stored without a leading `=`,
-    // matching how Excel writes it.
     if (column.totalsRowFormula !== undefined) {
         return `<tableColumn ${attrs}><totalsRowFormula>${escapeText(column.totalsRowFormula)}</totalsRowFormula></tableColumn>`;
     }
     return `<tableColumn ${attrs}/>`;
 }
-// OOXML booleans spell false as "0" or "false"; every other spelling (including "1"/"true") is true.
 function parseOoxmlBool(value) {
     return value !== '0' && value !== 'false';
 }
-/**
- * Parse a `<table>` part into the options that reconstruct it, or `undefined` when the XML is not a
- * usable table (no name, no ref, or no columns — Excel treats such a part as corrupt, so we drop it
- * rather than fabricate a degenerate table). Duplicate column names are not resolved here — the
- * {@link Table} constructor disambiguates them, so authoring and loading share one implementation.
- */
 export function parseTable(xml) {
     let name;
     let displayName;
     let ref;
-    let headerRowCount = 1; // OOXML default: a table carries a header row unless it says otherwise.
-    let totalsRowCount = 0; // OOXML default: no totals row.
-    let totalsRowShown; // Absent unless the part states the attribute.
-    let style; // Absent unless the part carries a `<tableStyleInfo>`.
-    let hasAutoFilter = false; // Only present when the part carries an `<autoFilter>` element.
+    let headerRowCount = 1;
+    let totalsRowCount = 0;
+    let totalsRowShown;
+    let style;
+    let hasAutoFilter = false;
     const columns = [];
-    // A `<totalsRowFormula>` is a text child of the current `<tableColumn>`, so it is captured across
-    // open/text/close rather than from an attribute. `calculatedColumnFormula` is a sibling child of
-    // the same type (CT_TableFormula), so guard on the exact element to avoid capturing its text.
     let inTotalsFormula = false;
     let totalsFormula = '';
     parseXml(xml, {
         onOpen(elementName, attrs) {
             switch (localName(elementName)) {
                 case 'table':
-                    // OOXML makes `displayName` the required identifier and `name` an optional alias; the
-                    // model inverts the roles (`name` is the formula identifier, `displayName` the label),
-                    // so read each from its own attribute and fall back across the pair when one is absent.
                     name = attrs.name ?? attrs.displayName;
                     displayName = attrs.displayName ?? attrs.name;
                     ref = attrs.ref;
@@ -114,8 +81,6 @@ export function parseTable(xml) {
                         headerRowCount = Number(attrs.headerRowCount);
                     if (attrs.totalsRowCount !== undefined)
                         totalsRowCount = Number(attrs.totalsRowCount);
-                    // Capture the flag verbatim so it re-emits exactly (or, absent, stays absent) rather
-                    // than being normalised.
                     if (attrs.totalsRowShown !== undefined)
                         totalsRowShown = parseOoxmlBool(attrs.totalsRowShown);
                     break;
@@ -123,8 +88,6 @@ export function parseTable(xml) {
                     hasAutoFilter = true;
                     break;
                 case 'tableStyleInfo': {
-                    // Keep each attribute off the literal so an absent one stays absent (not `key: undefined`),
-                    // preserving the round-trip — the writer re-emits only the attributes we actually saw.
                     const captured = {};
                     if (attrs.name !== undefined)
                         captured.name = attrs.name;
@@ -146,9 +109,6 @@ export function parseTable(xml) {
                     const column = { name: attrs.name };
                     if (attrs.totalsRowLabel !== undefined)
                         column.totalsRowLabel = attrs.totalsRowLabel;
-                    // An unrecognised totalsRowFunction is dropped rather than trusted in verbatim — the token
-                    // is a closed OOXML enumeration, so a foreign value is malformed input, not a future Excel
-                    // addition to accommodate.
                     if (attrs.totalsRowFunction !== undefined &&
                         isTotalsRowFunction(attrs.totalsRowFunction)) {
                         column.totalsRowFunction = attrs.totalsRowFunction;
@@ -170,9 +130,6 @@ export function parseTable(xml) {
             if (localName(elementName) !== 'totalsRowFormula')
                 return;
             inTotalsFormula = false;
-            // Attach to the column currently being parsed — the last one pushed. Excel writes the child
-            // only for `totalsRowFunction="custom"`, so a formula on any other column is meaningless, but
-            // preserving whatever the part carried keeps the round-trip faithful rather than second-guessing.
             const column = columns[columns.length - 1];
             if (column !== undefined)
                 column.totalsRowFormula = totalsFormula;
@@ -194,12 +151,8 @@ export function parseTable(xml) {
         rowCount: Math.max(0, dataRows),
         headerRow,
         totalsRow,
-        // Reconstruct the autoFilter state explicitly from the part: a header table read without an
-        // `<autoFilter>` must not have one fabricated on the next write.
         autoFilter: hasAutoFilter,
     };
-    // Kept off the literal so an absent attribute stays absent (not `totalsRowShown: undefined`),
-    // preserving the round-trip: a table that never stated the flag must not gain one.
     if (totalsRowShown !== undefined)
         options.totalsRowShown = totalsRowShown;
     if (style !== undefined)

package/dist/io/xlsx/threaded-comments.js

@@ -1,44 +1,12 @@
-// Modern threaded comments — the review-style conversations Excel has written since 2018, read from and
-// written to their two parts: `xl/threadedComments/threadedComment{n}.xml` (per sheet) and
-// `xl/persons/person.xml` (per workbook, the author registry).
-//
-// These are a Microsoft extension, not base ECMA-376, and they are a *separate* feature from legacy
-// notes (`comments{n}.xml`, see `comments.ts`) rather than a newer spelling of them. A cell carries
-// one or the other, never both — Excel refuses to add a note to a threaded cell and vice versa.
-//
-// A message identifies its author by `personId` into the registry and its thread by `id`/`parentId`:
-// the first message of a thread has no `parentId`, every reply carries the head's `id`. Only the head
-// carries `done`, so a thread's resolved state is its head's — a reply never says.
-//
-// These parsers describe a file that already exists, so they read leniently: an unrecognised or
-// missing attribute yields a sensible default rather than a throw, and a message too incomplete to
-// anchor is skipped instead of crashing the read. Optional wire attributes stay optional in the
-// parsed shape rather than collapsing to `''`, so "the file did not say" never masquerades as a value
-// the file contained.
-//
-// {@link buildCommentThreads} turns the flat message list into the model's threads, resolving each
-// author and mention against the workbook's person registry. That grouping is deliberately not the
-// parsers' job: they stay faithful to the part, one function per wire form.
-//
-// The writers are the exact inverse and carry no clock and no id generator: every guid and every
-// timestamp is written from the model, verbatim, so the same workbook always serialises to the same
-// bytes. A conversation Excel wrote round-trips as itself; one authored in the model carries whatever
-// ids and dates the caller supplied.
 import { decodeAddress } from '../../core/address.js';
 import { MENTION_OFFSET_MAX, } from '../../core/comment-thread.js';
 import { escapeAttr, escapeText, XML_DECLARATION } from '../../xml/xml.js';
 import { boolStrict, localName, parseXml } from '../../xml/xml-read.js';
 import { THREADED_COMMENTS_NS } from './namespaces.js';
-/**
- * Parse `xl/persons/person.xml` into its registered authors, in document order. Order carries no
- * meaning — Excel re-sorts the list by person id when it saves — so nothing may depend on it. An
- * entry without an `id` is skipped: no message could reference it.
- */
 export function parsePersons(xml) {
     const persons = [];
     parseXml(xml, {
         onOpen(name, attrs) {
-            // `personList` shares the prefix, so match the exact local name rather than a `startsWith`.
             if (localName(name) !== 'person')
                 return;
             const { id, displayName, userId, providerId } = attrs;
@@ -54,15 +22,7 @@ export function parsePersons(xml) {
     });
     return persons;
 }
-// Committing a message from its close handling alone would silently drop `<threadedComment …/>`,
-// which fires no close of its own; presenting the self-closing form as an empty element gives it one.
 const THREADED_COMMENT_EMPTY_CLOSES = new Set(['threadedComment']);
-/**
- * Parse a `threadedComment{n}.xml` part into its messages, in document order — thread order, with
- * each thread's replies following its head. Grouping into threads is {@link buildCommentThreads}'s
- * job; this stays faithful to the part. A message without a `ref` or `id` cannot be anchored or
- * replied to and is skipped.
- */
 export function parseThreadedComments(xml) {
     const messages = [];
     let open;
@@ -124,21 +84,12 @@ function threadedCommentFrom(attrs, text, mentions) {
         ...(parentId !== undefined ? { parentId } : {}),
     };
 }
-// A mention without a target person or a usable span cannot be resolved or rendered, so it is dropped
-// rather than carried as a mention over nothing — a `length` of 0 would be an invisible chip, and a
-// negative or non-numeric offset would place it outside the text it is supposed to cover.
-//
-// The upper bound is what makes this a hostile-input guard rather than a tidiness check: an offset the
-// wire cannot express would be re-emitted by the writer as an invalid attribute — and JavaScript spells a
-// large enough number in exponent form (`1e+21`), which no schema accepts at all — costing the reader's
-// leniency the entire conversation when Excel repairs the part. Dropping the chip costs a highlight.
 function mentionFrom(attrs) {
     const personId = attrs.mentionpersonId;
     const startIndex = integerAttribute(attrs.startIndex);
     const length = integerAttribute(attrs.length);
     if (personId === undefined || startIndex === undefined || length === undefined)
         return undefined;
-    // A negative offset points outside the text and a zero length spans nothing, so neither could render.
     if (startIndex < 0 || length <= 0)
         return undefined;
     if (startIndex > MENTION_OFFSET_MAX || length > MENTION_OFFSET_MAX)
@@ -150,26 +101,14 @@ function mentionFrom(attrs) {
         ...(attrs.mentionId !== undefined ? { mentionId: attrs.mentionId } : {}),
     };
 }
-// An integer attribute, or undefined when the file did not write a usable one. Blank is rejected before
-// `Number` sees it, since `Number('')` is 0 — an empty attribute must not read as offset zero.
 function integerAttribute(raw) {
     if (raw === undefined || raw.trim() === '')
         return undefined;
     const value = Number(raw);
     return Number.isInteger(value) ? value : undefined;
 }
-/**
- * Group a part's messages into the model's threads, resolving every author and mention against the
- * workbook's person registry (`personById`, typically `Workbook.getPerson`).
- *
- * Document order is thread order with each thread's replies following its head, so one pass suffices: a
- * message with no `parentId` opens a thread, and a reply joins the thread its `parentId` names. A reply
- * whose parent is unknown — a dangling `parentId` no Excel file produces — opens a thread of its own
- * rather than being dropped, so a foreign generator's damage costs structure, never content.
- */
 export function buildCommentThreads(messages, personById) {
     const threads = [];
-    // The head's own message list, so a reply appends to the thread already published in `threads`.
     const commentsByHeadId = new Map();
     for (const message of messages) {
         const comment = commentFrom(message, personById);
@@ -183,15 +122,10 @@ export function buildCommentThreads(messages, personById) {
             continue;
         const comments = [comment];
         commentsByHeadId.set(message.id, comments);
-        // Resolved is the head's flag: a reply never carries `done`, so it never contradicts its thread.
         threads.push({ ref, resolved: message.done, comments });
     }
     return threads;
 }
-// The canonical A1 form of a thread's anchor, or undefined when the file wrote something that cannot
-// anchor one — a range, a bare row or column, or outright garbage. Canonicalising here is what lets
-// every later consumer compare anchors as plain strings (`$B$2` and `B2` are one cell) and keeps a
-// foreign file's malformed reference out of the writer, which anchors the thread's legacy fallback by it.
 function anchorRef(reference) {
     let decoded;
     try {
@@ -223,18 +157,6 @@ function mentionOf(mention, personById) {
         ...(mention.mentionId !== undefined ? { mentionId: mention.mentionId } : {}),
     };
 }
-/**
- * Serialise one sheet's conversations into its `xl/threadedComments/threadedComment{n}.xml` part.
- *
- * Messages are written flat, in thread order with each thread's replies after its head — the shape
- * {@link parseThreadedComments} reads back. The head/reply distinction the model holds as array position
- * becomes `parentId` on every reply but the head, and `done="1"` goes on the head alone: only the head
- * carries the flag on the wire, so a reply can never contradict the thread it belongs to. An open thread
- * omits `done` entirely rather than writing `done="0"`, exactly as Excel does.
- *
- * A thread with no messages writes nothing: it has neither text to say nor a head id for its replies and
- * its legacy fallback to hang off.
- */
 export function threadedCommentsXml(threads) {
     const messages = threads.flatMap((thread) => {
         const [head, ...replies] = thread.comments;
@@ -248,11 +170,6 @@ export function threadedCommentsXml(threads) {
     return (XML_DECLARATION +
         `<ThreadedComments xmlns="${THREADED_COMMENTS_NS}">${messages.join('')}</ThreadedComments>`);
 }
-// One `<threadedComment>`. `tail` is the attribute that distinguishes the message's role — `done` for a
-// resolved head, `parentId` for a reply, nothing for an open head. A `dT` or `personId` the model never
-// held is omitted rather than written empty, so "the file did not say" stays distinguishable from "the
-// file said nothing". Every value is escaped: an authored message's text and a foreign file's ids alike
-// are untrusted, and an unescaped `"` would end the attribute and reshape the part.
 function threadedCommentXml(ref, comment, tail) {
     const date = comment.date === undefined ? '' : ` dT="${escapeAttr(comment.date)}"`;
     const person = comment.personId === undefined ? '' : ` personId="${escapeAttr(comment.personId)}"`;
@@ -261,21 +178,10 @@ function threadedCommentXml(ref, comment, tail) {
         mentionsXml(comment.mentions) +
         '</threadedComment>');
 }
-// The `<mentions>` block, which follows `<text>` in the message. All four `<mention>` attributes are
-// required — verified by dropping each in turn and getting `Sch_MissRequiredAttribute` — so a mention the
-// model holds without a `mentionId`, or with a span the wire cannot express, cannot be written at all. It
-// is dropped rather than given an invented id or a clamped span: the `@name` stays in the text and only
-// the chip is lost, whereas an invalid part risks Excel repairing the whole conversation away.
-//
-// The bounds check is deliberately here as well as in the reader. Both the authoring verb and the parser
-// already refuse an out-of-range offset, so nothing should reach this — but `restoreCommentThreads` takes
-// a model wholesale, and a serialiser that *cannot* emit `length="1e+21"` beats one that merely is not
-// currently handed one.
 function mentionsXml(mentions) {
     const entries = mentions.flatMap(({ personId, mentionId, startIndex, length }) => {
         if (mentionId === undefined)
             return [];
-        // A zero-length span is in range but renders nothing, so it is no more writable than one out of range.
         if (!writableOffset(startIndex) || !writableOffset(length) || length === 0)
             return [];
         return [
@@ -285,18 +191,9 @@ function mentionsXml(mentions) {
     });
     return entries.length === 0 ? '' : `<mentions>${entries.join('')}</mentions>`;
 }
-// An offset the wire can express: a whole number within the schema's UInt32 ceiling.
 function writableOffset(value) {
     return Number.isInteger(value) && value >= 0 && value <= MENTION_OFFSET_MAX;
 }
-/**
- * Serialise the workbook's identity registry into `xl/persons/person.xml` — singular and unnumbered,
- * unlike the per-sheet thread parts.
- *
- * Entries are written in registry order, which carries no meaning: Excel re-sorts the list by person id
- * whenever it saves, so this only has to be deterministic, not canonical. `userId`/`providerId` are
- * written when the model holds them; a registry read from a file holds whatever that file stated.
- */
 export function personsXml(persons) {
     const entries = persons.map((person) => {
         const userId = person.userId === undefined ? '' : ` userId="${escapeAttr(person.userId)}"`;

package/dist/io/xlsx/workbook-xml.js

@@ -1,6 +1,3 @@
-// Workbook-level serialisation: the package's `[Content_Types].xml`, its root and workbook `.rels`
-// parts, `xl/workbook.xml` (sheets, defined names, calc/protection settings, pivot-cache and slicer
-// registrations), and the `docProps` core/app property parts.
 import { mangleFormula, quoteSheetName } from '../../core/formula.js';
 import { WORKBOOK_PROTECTION_CREDENTIAL_ATTRS } from '../../core/workbook-protection.js';
 import { escapeAttr, escapeText, XML_DECLARATION } from '../../xml/xml.js';
@@ -27,15 +24,10 @@ const CT = {
     pivotTable: 'application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml',
     pivotCacheDefinition: 'application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml',
     pivotCacheRecords: 'application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml',
-    // Both threaded-comment parts are Microsoft extensions, hence the `vnd.ms-excel` vendor prefix rather
-    // than the `openxmlformats-officedocument` one every standard part carries.
     threadedComments: 'application/vnd.ms-excel.threadedcomments+xml',
     person: 'application/vnd.ms-excel.person+xml',
 };
 export function contentTypesXml(sheetCount, tables, commentNumbers, drawingNumbers, printerSettingsNumbers, mediaExtensions, hasSharedStrings, preservedParts, pivots, preservedWorkbookRefs, threadedCommentNumbers, hasPersons) {
-    // One extension→default-content-type map both halves read: the defaults render it, the overrides
-    // correct any preserved part whose own type differs from its extension's default. Sharing it is what
-    // keeps a `<Default>` and its `<Override>`s from ever disagreeing.
     const extensionDefaults = buildExtensionDefaults(commentNumbers, printerSettingsNumbers, mediaExtensions, preservedParts);
     return (XML_DECLARATION +
         `<Types xmlns="${NS.contentTypes}">` +
@@ -43,12 +35,6 @@ export function contentTypesXml(sheetCount, tables, commentNumbers, drawingNumbe
         contentTypeOverrides(sheetCount, tables, drawingNumbers, commentNumbers, hasSharedStrings, preservedParts, pivots, preservedWorkbookRefs, extensionDefaults, threadedCommentNumbers, hasPersons) +
         '</Types>');
 }
-// The content type declared at the `<Default>` level for each file extension the package carries, in
-// emission order: the built-in rels/xml pair, the vml/bin/image kinds the writer itself generates,
-// then one default per *new* extension a preserved binary part introduces (first part of an extension
-// wins). Keys are lower-cased for case-insensitive extension matching; each value keeps the extension
-// token as it will be emitted so rendering stays byte-stable. A preserved `.xml` part is deliberately
-// left out — it always carries its own type as a per-part override, never a generic `xml` default.
 function buildExtensionDefaults(commentNumbers, printerSettingsNumbers, mediaExtensions, preservedParts) {
     const defaults = new Map();
     const add = (extension, contentType) => {
@@ -72,36 +58,16 @@ function buildExtensionDefaults(commentNumbers, printerSettingsNumbers, mediaExt
     }
     return defaults;
 }
-// A macro-enabled workbook's own VBA project is round-tripped as a preserved workbook reference
-// (see `isPreservedWorkbookRelType` in read.ts), so its presence is what distinguishes a re-emitted
-// .xlsm from a plain .xlsx: `xl/workbook.xml` must declare the macro-enabled content type or Excel
-// flags the package as needing repair on open.
 function isMacroEnabled(preservedWorkbookRefs) {
     return preservedWorkbookRefs.some((ref) => ref.relType.endsWith('/vbaProject'));
 }
-// The extension-level `<Default>` declarations, rendered from the shared extension-default map (see
-// {@link buildExtensionDefaults}) in insertion order. The raw bytes of a VML, a printer-settings blob,
-// or an image carry no XML content type of their own, so each is declared once per extension rather
-// than per part; a preserved binary part whose type differs from its extension's default is corrected
-// by a per-part `<Override>` in {@link contentTypeOverrides}.
 function contentTypeDefaults(extensionDefaults) {
     return [...extensionDefaults.values()]
         .map(({ extension, contentType }) => defaultType(extension, contentType))
         .join('');
 }
-// The per-part `<Override>` declarations, in canonical package order: workbook, worksheets, tables,
-// drawings, comments, the threaded-comment parts, each pivot's three parts, theme, styles, the optional
-// shared strings and threaded-comment person registry, the doc-props pair, then any preserved part whose
-// content type its extension's `<Default>` does not already carry — every `.xml` part (the generic `xml`
-// default never matches a real part type) and any binary part sharing an extension with a differently-typed
-// sibling (a `vbaProjectSignature.bin` next to a `vbaProject.bin`), which a lone extension default would
-// otherwise mis-type.
 function contentTypeOverrides(sheetCount, tables, drawingNumbers, commentNumbers, hasSharedStrings, preservedParts, pivots, preservedWorkbookRefs, extensionDefaults, threadedCommentNumbers, hasPersons) {
     const preservedOverrides = preservedParts
-        // A preserved theme lands at the fixed theme path, whose override is already in the list below —
-        // and OPC forbids declaring the same PartName twice. The fixed declaration is the right one to
-        // keep: the part reached the model through a `.../theme` relationship, so its type is the theme
-        // type whatever the source package happened to declare.
         .filter((part) => part.path !== THEME_PART_PATH)
         .filter((part) => extensionDefaults.get(extensionOf(part.path).toLowerCase())?.contentType !==
         part.contentType)
@@ -128,15 +94,9 @@ function contentTypeOverrides(sheetCount, tables, drawingNumbers, commentNumbers
 function override(partName, contentType) {
     return `<Override PartName="${partName}" ContentType="${contentType}"/>`;
 }
-// A `<Default>` content-type declaration binding a file extension to the type every part with that
-// extension carries — the extension-level counterpart to {@link override}'s per-part declaration.
 function defaultType(extension, contentType) {
     return `<Default Extension="${extension}" ContentType="${contentType}"/>`;
 }
-// The package root relationships: the three the writer regenerates from the model (the office
-// document and the core/app properties), followed by any preserved root references — customUI ribbon
-// parts, custom properties, a thumbnail — re-declared with fresh ids past the fixed three so a
-// round-trip keeps content wired from `_rels/.rels` that the model does not otherwise emit.
 export function rootRelsXml(rootRefs) {
     return relationshipsPart([
         relationship('rId1', REL.officeDocument, 'xl/workbook.xml'),
@@ -165,12 +125,6 @@ export function workbookXml(workbook, preservedRels, pivots) {
         workbookExtLstXml(preservedRels) +
         '</workbook>');
 }
-// `<bookViews>` follows `<workbookProtection>` and precedes `<sheets>` in CT_Workbook order. Unlike
-// every other optional block here it is emitted unconditionally: a consumer restores the document
-// window from this rect and lays the sheet's panes out inside it, so a package without one leaves a
-// frozen split measured against an uninitialised window (see `DEFAULT_WORKBOOK_VIEW`). The
-// visibility and minimised flags are written only when they differ from the schema default, and
-// `activeTab` only for a non-first sheet — exactly the shape Excel writes for an ordinary window.
 function bookViewsXml(workbook) {
     const view = workbook.view;
     const activeTab = workbook.activeTabIndex;
@@ -182,12 +136,6 @@ function bookViewsXml(workbook) {
         (activeTab === 0 ? '' : ` activeTab="${activeTab}"`);
     return `<bookViews><workbookView${attrs}/></bookViews>`;
 }
-// The `<externalReferences>` element registers each preserved external link (a link to a source
-// workbook), wired to the relationship reaching its `externalLink` part. It follows `<sheets>` in
-// CT_Workbook order and precedes `<definedNames>`; its child order is the `[n]` index a formula or
-// defined name resolves an external cell through, so entries are emitted by their captured
-// `externalReferenceIndex` — keeping every `[1]`, `[2]`, … pointing at the same linked workbook it did
-// before the round-trip. '' when no external link was preserved.
 function externalReferencesXml(preservedRels) {
     const links = preservedRels
         .filter((ref) => ref.externalReferenceIndex !== undefined)
@@ -197,10 +145,6 @@ function externalReferencesXml(preservedRels) {
     const entries = links.map((ref) => `<externalReference r:id="${ref.relId}"/>`).join('');
     return `<externalReferences>${entries}</externalReferences>`;
 }
-// The workbook-body `<x14:slicerCaches>` extension that registers each preserved slicer cache, wired
-// to the relationship reaching its cache part. Slicer caches (unlike pivot caches, which register in
-// `<pivotCaches>`) live only in this extension block, so re-emitting it is what lets Excel rediscover
-// the slicers. `<extLst>` is the final child of CT_Workbook. '' when no slicer cache was preserved.
 function workbookExtLstXml(preservedRels) {
     const caches = preservedRels.filter((ref) => ref.relType.endsWith('/slicerCache'));
     if (caches.length === 0)
@@ -208,11 +152,6 @@ function workbookExtLstXml(preservedRels) {
     const entries = caches.map((ref) => `<x14:slicerCache r:id="${ref.relId}"/>`).join('');
     return `<extLst>${x14Ext(SLICER_CACHES_EXT_URI, `<x14:slicerCaches>${entries}</x14:slicerCaches>`)}</extLst>`;
 }
-// The `<pivotCaches>` element registers each pivot cache under the `cacheId` a pivot table resolves
-// its cache through, wired to the relationship that reaches the cache definition. It follows
-// `<calcPr>` in CT_Workbook order and carries both preserved caches (passed through from a read file)
-// and caches the writer generated for modeled pivot tables. A slicer cache (no `cacheId`) is
-// registered in a workbook extension block, not here, so it is skipped.
 function pivotCachesXml(preservedRels, pivots) {
     const preserved = preservedRels
         .filter((ref) => ref.pivotCacheId !== undefined)
@@ -223,10 +162,6 @@ function pivotCachesXml(preservedRels, pivots) {
         return '';
     return `<pivotCaches>${entries.join('')}</pivotCaches>`;
 }
-// `<workbookProtection>` precedes `<sheets>` in CT_Workbook order. It re-emits the workbook's
-// structure/window lock flags (each written only when true, so an unlocked aspect stays absent) and
-// the preserved password/agile-hash credential attributes verbatim. Emitted only when the workbook
-// actually declares protection — the flags or a credential — so an unprotected workbook stays clean.
 function workbookProtectionXml(workbook) {
     const p = workbook.protection;
     if (p === undefined)
@@ -247,24 +182,10 @@ function workbookProtectionXml(workbook) {
         return '';
     return `<workbookProtection ${attrs.join(' ')}/>`;
 }
-// The `calcId` desktop Excel stamps into `<calcPr>` — the build number of the calc engine that last
-// evaluated the workbook. Consumers only compare it to decide whether cached results are stale; we
-// emit a fixed recent value alongside `fullCalcOnLoad`, which already forces a full recalculation.
 const EXCEL_CALC_ID = '171027';
-// `<calcPr>` follows `<definedNames>` in CT_Workbook order and carries the calculation settings.
-// Today the model exposes a single one: `fullCalcOnLoad`, which tells the consumer to recalculate
-// every formula on open instead of trusting the cached results. Emitted only when set, so an
-// unmarked workbook keeps the element (and its `calcId`) out of the file entirely.
 function calcPrXml(workbook) {
     return workbook.fullCalcOnLoad ? `<calcPr calcId="${EXCEL_CALC_ID}" fullCalcOnLoad="1"/>` : '';
 }
-// The `<definedNames>` block follows `<sheets>` in the schema. A sheet-scoped name carries a
-// `localSheetId` — the 0-based position of its sheet among the `<sheet>` entries, NOT the sheet's
-// own id — so the index is resolved against the worksheet order here. The refersTo formula is the
-// element's text content, run through the same `_xlfn.` function mangling the writer applies to a
-// cell formula so a name defined as a modern function (a LAMBDA, an XLOOKUP-based name) is stored
-// under the prefix Excel requires; a plain reference has no function call and passes through
-// untouched. Only names that are actually set emit anything.
 function definedNamesXml(workbook) {
     const sheets = workbook.worksheets;
     const userEntries = workbook.definedNames.map((name) => {
@@ -276,10 +197,6 @@ function definedNamesXml(workbook) {
         return (`<definedName name="${escapeAttr(name.name)}"${scopeAttr}${commentAttr}${hiddenAttr}>` +
             `${escapeText(mangleFormula(name.refersTo))}</definedName>`);
     });
-    // Every sheet-level autofilter contributes the hidden, sheet-scoped `_FilterDatabase` built-in that
-    // Excel derives from its range. The reader drops these on load and rebuilds them from the sheet's
-    // `<autoFilter>`, so `Worksheet.autoFilter` stays the single source of truth and a round-trip never
-    // duplicates them.
     const filterEntries = sheets.flatMap((sheet, index) => sheet.autoFilter === undefined
         ? []
         : [
@@ -291,17 +208,10 @@ function definedNamesXml(workbook) {
         return '';
     return `<definedNames>${entries.join('')}</definedNames>`;
 }
-// Build the sheet-qualified, fully-absolute reference a `_FilterDatabase` name carries
-// (`'Sheet 1'!$A$1:$C$10`) from a sheet name and its already-canonical `A1:C10` autofilter range.
 function filterDatabaseRefersTo(sheetName, range) {
     const absolute = range.replace(/([A-Z]+)(\d+)/g, '$$$1$$$2');
     return `${quoteSheetName(sheetName)}!${absolute}`;
 }
-// The relationships the workbook part always carries after its per-sheet rels: `styles.xml` and
-// `theme/theme1.xml`. Their count anchors every downstream rel id — `sharedStrings.xml` and the
-// threaded-comment person registry (when present), then the preserved/pivot caches — so `write.ts`
-// derives its `workbookRelBase` from this same constant rather than repeating the literal and risking
-// drift.
 export const FIXED_WORKBOOK_REL_COUNT = 2;
 export function workbookRelsXml(sheetCount, hasSharedStrings, personsRelId, preservedRels, pivots) {
     return relationshipsPart([
@@ -313,14 +223,10 @@ export function workbookRelsXml(sheetCount, hasSharedStrings, personsRelId, pres
                 relationship(`rId${sheetCount + FIXED_WORKBOOK_REL_COUNT + 1}`, REL.sharedStrings, 'sharedStrings.xml'),
             ]
             : []),
-        // The threaded-comment identity registry every conversation on every sheet resolves its authors and
-        // @mentions through. Workbook-level and singular, so this one relationship serves all the sheets.
         ...(personsRelId === null
             ? []
             : [relationship(personsRelId, REL.person, 'persons/person.xml')]),
-        // A preserved cache's target is package-absolute; express it relative to the workbook part.
         ...preservedRels.map((ref) => relationship(ref.relId, ref.relType, escapeAttr(relativePartPath('xl/workbook.xml', ref.entryPath)))),
-        // A generated pivot cache's workbook relationship reaches its cache definition part.
         ...pivots.map((pivot) => relationship(pivot.workbookRelId, REL.pivotCacheDefinition, `pivotCache/pivotCacheDefinition${pivot.number}.xml`)),
     ]);
 }