@shbernal/ts-xlsx 1.2.0 → 2.0.0

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

@@ -0,0 +1,142 @@
+import { DEFAULT_THEME_COLOR_SCHEME, normalizeThemeColor, } from '../../core/theme.js';
+import { decodeEntities } from '../../xml/xml-read.js';
+import { escapeAttr } from '../../xml/xml.js';
+const SCHEME_SLOT = new RegExp('<a:(dk1|lt1|dk2|lt2|accent[1-6]|hlink|folHlink)\\b[^>]*>' + '\\s*<a:(srgbClr|sysClr)\\b([^>]*)>', 'g');
+export function parseThemeColorScheme(themeXml) {
+    const block = /<a:clrScheme\b[^>]*>([\s\S]*?)<\/a:clrScheme>/.exec(themeXml);
+    if (block === null)
+        return {};
+    const scheme = {};
+    for (const match of (block[1] ?? '').matchAll(SCHEME_SLOT)) {
+        const slot = match[1];
+        const attrs = match[3] ?? '';
+        const source = match[2] === 'sysClr' ? /\blastClr="([^"]*)"/ : /\bval="([^"]*)"/;
+        const value = source.exec(attrs)?.[1];
+        if (value !== undefined && /^[0-9a-fA-F]{6}$/.test(value))
+            scheme[slot] = value;
+    }
+    return scheme;
+}
+export function parseThemeFontScheme(themeXml) {
+    const block = /<a:fontScheme\b[^>]*>([\s\S]*?)<\/a:fontScheme>/.exec(themeXml);
+    if (block === null)
+        return {};
+    const face = (which) => {
+        const font = new RegExp(`<a:${which}\\b[^>]*>([\\s\\S]*?)</a:${which}>`).exec(block[1] ?? '');
+        const typeface = /<a:latin\b[^>]*\btypeface="([^"]*)"/.exec(font?.[1] ?? '')?.[1];
+        return typeface === undefined ? undefined : decodeEntities(typeface);
+    };
+    const scheme = {};
+    const major = face('majorFont');
+    const minor = face('minorFont');
+    if (major !== undefined)
+        scheme.major = major;
+    if (minor !== undefined)
+        scheme.minor = minor;
+    return scheme;
+}
+const SCHEME_ELEMENT_ORDER = [
+    'dk1',
+    'lt1',
+    'dk2',
+    'lt2',
+    'accent1',
+    'accent2',
+    'accent3',
+    'accent4',
+    'accent5',
+    'accent6',
+    'hlink',
+    'folHlink',
+];
+export function applyThemeOverrides(baseXml, overrides) {
+    let xml = baseXml;
+    const colors = overrides.colors ?? {};
+    if (Object.keys(colors).length > 0) {
+        const sourceElements = parseThemeColorElements(baseXml);
+        const body = SCHEME_ELEMENT_ORDER.map((slot) => {
+            const authored = colors[slot];
+            const inner = authored !== undefined
+                ? `<a:srgbClr val="${normalizeThemeColor(authored)}"/>`
+                : (sourceElements[slot] ??
+                    `<a:srgbClr val="${DEFAULT_THEME_COLOR_SCHEME[slot]}"/>`);
+            return `<a:${slot}>${inner}</a:${slot}>`;
+        }).join('');
+        xml = replaceBlockBody(xml, 'clrScheme', body);
+    }
+    const { major, minor } = overrides.fonts ?? {};
+    if (major !== undefined)
+        xml = replaceLatinTypeface(xml, 'majorFont', major);
+    if (minor !== undefined)
+        xml = replaceLatinTypeface(xml, 'minorFont', minor);
+    return xml;
+}
+function parseThemeColorElements(themeXml) {
+    const block = /<a:clrScheme\b[^>]*>([\s\S]*?)<\/a:clrScheme>/.exec(themeXml);
+    if (block === null)
+        return {};
+    const elements = {};
+    const pattern = /<a:(dk1|lt1|dk2|lt2|accent[1-6]|hlink|folHlink)>([\s\S]*?)<\/a:\1>|<a:(dk1|lt1|dk2|lt2|accent[1-6]|hlink|folHlink)\/>/g;
+    for (const match of (block[1] ?? '').matchAll(pattern)) {
+        const slot = (match[1] ?? match[3]);
+        const inner = match[2];
+        if (inner !== undefined && inner !== '')
+            elements[slot] = inner;
+    }
+    return elements;
+}
+function replaceBlockBody(xml, name, body) {
+    const pattern = new RegExp(`(<a:${name}\\b[^>]*>)[\\s\\S]*?(</a:${name}>)`);
+    return xml.replace(pattern, (_all, open, close) => `${open}${body}${close}`);
+}
+function replaceLatinTypeface(xml, which, typeface) {
+    const pattern = new RegExp(`(<a:${which}\\b[^>]*>[\\s\\S]*?<a:latin\\b)[^>]*(/>)`);
+    return xml.replace(pattern, (_all, open, close) => `${open} typeface="${escapeAttr(typeface)}"${close}`);
+}
+export const DEFAULT_THEME_XML = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' +
+    '<a:theme xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" name="Office Theme">' +
+    '<a:themeElements>' +
+    '<a:clrScheme name="Office">' +
+    '<a:dk1><a:sysClr val="windowText" lastClr="000000"/></a:dk1>' +
+    '<a:lt1><a:sysClr val="window" lastClr="FFFFFF"/></a:lt1>' +
+    '<a:dk2><a:srgbClr val="44546A"/></a:dk2>' +
+    '<a:lt2><a:srgbClr val="E7E6E6"/></a:lt2>' +
+    '<a:accent1><a:srgbClr val="4472C4"/></a:accent1>' +
+    '<a:accent2><a:srgbClr val="ED7D31"/></a:accent2>' +
+    '<a:accent3><a:srgbClr val="A5A5A5"/></a:accent3>' +
+    '<a:accent4><a:srgbClr val="FFC000"/></a:accent4>' +
+    '<a:accent5><a:srgbClr val="5B9BD5"/></a:accent5>' +
+    '<a:accent6><a:srgbClr val="70AD47"/></a:accent6>' +
+    '<a:hlink><a:srgbClr val="0563C1"/></a:hlink>' +
+    '<a:folHlink><a:srgbClr val="954F72"/></a:folHlink>' +
+    '</a:clrScheme>' +
+    '<a:fontScheme name="Office">' +
+    '<a:majorFont><a:latin typeface="Calibri Light" panose="020F0302020204030204"/><a:ea typeface=""/><a:cs typeface=""/></a:majorFont>' +
+    '<a:minorFont><a:latin typeface="Calibri" panose="020F0502020204030204"/><a:ea typeface=""/><a:cs typeface=""/></a:minorFont>' +
+    '</a:fontScheme>' +
+    '<a:fmtScheme name="Office">' +
+    '<a:fillStyleLst>' +
+    '<a:solidFill><a:schemeClr val="phClr"/></a:solidFill>' +
+    '<a:gradFill rotWithShape="1"><a:gsLst><a:gs pos="0"><a:schemeClr val="phClr"><a:lumMod val="110000"/><a:satMod val="105000"/><a:tint val="67000"/></a:schemeClr></a:gs><a:gs pos="50000"><a:schemeClr val="phClr"><a:lumMod val="105000"/><a:satMod val="103000"/><a:tint val="73000"/></a:schemeClr></a:gs><a:gs pos="100000"><a:schemeClr val="phClr"><a:lumMod val="105000"/><a:satMod val="109000"/><a:tint val="81000"/></a:schemeClr></a:gs></a:gsLst><a:lin ang="5400000" scaled="0"/></a:gradFill>' +
+    '<a:gradFill rotWithShape="1"><a:gsLst><a:gs pos="0"><a:schemeClr val="phClr"><a:satMod val="103000"/><a:lumMod val="102000"/><a:tint val="94000"/></a:schemeClr></a:gs><a:gs pos="50000"><a:schemeClr val="phClr"><a:satMod val="110000"/><a:lumMod val="100000"/><a:shade val="100000"/></a:schemeClr></a:gs><a:gs pos="100000"><a:schemeClr val="phClr"><a:lumMod val="99000"/><a:satMod val="120000"/><a:shade val="78000"/></a:schemeClr></a:gs></a:gsLst><a:lin ang="5400000" scaled="0"/></a:gradFill>' +
+    '</a:fillStyleLst>' +
+    '<a:lnStyleLst>' +
+    '<a:ln w="6350" cap="flat" cmpd="sng" algn="ctr"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill><a:prstDash val="solid"/><a:miter lim="800000"/></a:ln>' +
+    '<a:ln w="12700" cap="flat" cmpd="sng" algn="ctr"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill><a:prstDash val="solid"/><a:miter lim="800000"/></a:ln>' +
+    '<a:ln w="19050" cap="flat" cmpd="sng" algn="ctr"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill><a:prstDash val="solid"/><a:miter lim="800000"/></a:ln>' +
+    '</a:lnStyleLst>' +
+    '<a:effectStyleLst>' +
+    '<a:effectStyle><a:effectLst/></a:effectStyle>' +
+    '<a:effectStyle><a:effectLst/></a:effectStyle>' +
+    '<a:effectStyle><a:effectLst><a:outerShdw blurRad="57150" dist="19050" dir="5400000" rotWithShape="0"><a:srgbClr val="000000"><a:alpha val="63000"/></a:srgbClr></a:outerShdw></a:effectLst></a:effectStyle>' +
+    '</a:effectStyleLst>' +
+    '<a:bgFillStyleLst>' +
+    '<a:solidFill><a:schemeClr val="phClr"/></a:solidFill>' +
+    '<a:solidFill><a:schemeClr val="phClr"><a:tint val="95000"/><a:satMod val="170000"/></a:schemeClr></a:solidFill>' +
+    '<a:gradFill rotWithShape="1"><a:gsLst><a:gs pos="0"><a:schemeClr val="phClr"><a:tint val="93000"/><a:satMod val="150000"/><a:shade val="98000"/><a:lumMod val="102000"/></a:schemeClr></a:gs><a:gs pos="50000"><a:schemeClr val="phClr"><a:tint val="98000"/><a:satMod val="130000"/><a:shade val="90000"/><a:lumMod val="103000"/></a:schemeClr></a:gs><a:gs pos="100000"><a:schemeClr val="phClr"><a:shade val="63000"/><a:satMod val="120000"/></a:schemeClr></a:gs></a:gsLst><a:lin ang="5400000" scaled="0"/></a:gradFill>' +
+    '</a:bgFillStyleLst>' +
+    '</a:fmtScheme>' +
+    '</a:themeElements>' +
+    '<a:objectDefaults/>' +
+    '<a:extraClrSchemeLst/>' +
+    '</a:theme>';

package/dist/io/xlsx/threaded-comments.d.ts

@@ -1,5 +1,5 @@
-import { type CommentThread, type Person } from '../../core/comment-thread.ts';
-/** A registered author of threaded comments — one `<person>` of `xl/persons/person.xml`. */
+import { type CommentThread, type MentionRef, type Person } from '../../core/comment-thread.ts';
+/** A registered author of threaded comments: one `<person>` of `xl/persons/person.xml`. */
 export interface ParsedPerson {
     /** Brace-wrapped GUID a message's `personId` points at. */
     readonly id: string;
@@ -10,26 +10,17 @@ export interface ParsedPerson {
     readonly providerId?: string;
 }
 /**
- * One `<mention>` of a message's `<mentions>` block: who was named, and the run of the message text
- * that renders as the mention chip.
+ * One `<mention>` of a message's `<mentions>` block: the model's own {@link MentionRef}, which is
+ * exactly the four wire attributes with nothing resolved yet. Declaring it a second time here would
+ * be two places for the offset convention to drift, and the offsets are what a spreadsheet app
+ * highlights with.
  *
- * All four wire attributes are required (Excel rejects a file missing any), and note the lowercase `p`
- * in `mentionpersonId` — the capitalised spelling is not a declared attribute.
+ * All four attributes are required (Excel rejects a file missing any), and note the lowercase `p`
+ * in `mentionpersonId`; the capitalised spelling is not a declared attribute. The person id is that
+ * attribute's value; every other field is named as the model names it.
  */
-export interface ParsedMention {
-    /** The mentioned {@link ParsedPerson.id}, from `mentionpersonId`. */
-    readonly personId: string;
-    /** Excel's own id for the mention itself. Absent only in a file that omitted it. */
-    readonly mentionId?: string;
-    /**
-     * 0-based character offset into the message text. Verified against desktop Excel by rendering: the
-     * chip covers exactly `[startIndex, startIndex + length)` of the text.
-     */
-    readonly startIndex: number;
-    /** The mention's length in characters, **including the leading `@`** (`@Grace Hopper` is 13). */
-    readonly length: number;
-}
-/** One message of a threaded conversation — a `<threadedComment>` of a `threadedComment{n}.xml`. */
+export type ParsedMention = MentionRef;
+/** One message of a threaded conversation: a `<threadedComment>` of a `threadedComment{n}.xml`. */
 export interface ParsedThreadedComment {
     /** A1 reference of the cell the whole thread anchors to; every message of a thread repeats it. */
     readonly ref: string;
@@ -39,7 +30,7 @@ export interface ParsedThreadedComment {
     readonly personId?: string;
     /**
      * The `dT` timestamp verbatim. Excel writes local wall-clock with fractional seconds and no
-     * timezone (`2026-07-24T10:56:41.72`), which is not a round-trippable instant — keeping the
+     * timezone (`2026-07-24T10:56:41.72`), which is not a round-trippable instant. Keeping the
      * string spares the reader from inventing a zone the file never stated.
      */
     readonly date?: string;
@@ -48,7 +39,7 @@ export interface ParsedThreadedComment {
     readonly parentId?: string;
     /**
      * The `done` flag exactly as written. Excel puts it on the head alone and omits it entirely on an
-     * open thread (never `done="0"`), so read a thread's resolved state off its head — a reply's
+     * open thread (never `done="0"`), so read a thread's resolved state off its head: a reply's
      * `false` here means "did not say", not "not resolved".
      */
     readonly done: boolean;
@@ -57,12 +48,12 @@ export interface ParsedThreadedComment {
 }
 /**
  * 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
+ * meaning, because 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 declare function parsePersons(xml: string): ParsedPerson[];
 /**
- * Parse a `threadedComment{n}.xml` part into its messages, in document order — thread order, with
+ * 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.
@@ -74,14 +65,14 @@ export declare function parseThreadedComments(xml: string): ParsedThreadedCommen
  *
  * 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
+ * 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 declare function buildCommentThreads(messages: readonly ParsedThreadedComment[], personById: (id: string) => Person | undefined): CommentThread[];
 /**
  * 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
+ * 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
@@ -92,7 +83,7 @@ export declare function buildCommentThreads(messages: readonly ParsedThreadedCom
  */
 export declare function threadedCommentsXml(threads: readonly CommentThread[]): string;
 /**
- * Serialise the workbook's identity registry into `xl/persons/person.xml` — singular and unnumbered,
+ * 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

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

@@ -1,7 +1,7 @@
-import { decodeAddress } from '../../core/address.js';
+import { encodeAddress, tryDecodeCellRef } 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 { boolStrict, decodeSpreadsheetText, localName, numInteger, parseXml, } from '../../xml/xml-read.js';
+import { escapeAttr, escapeSpreadsheetText, XML_DECLARATION } from '../../xml/xml.js';
 import { THREADED_COMMENTS_NS } from './namespaces.js';
 export function parsePersons(xml) {
     const persons = [];
@@ -76,7 +76,7 @@ function threadedCommentFrom(attrs, text, mentions) {
     return {
         ref,
         id,
-        text,
+        text: decodeSpreadsheetText(text),
         done: boolStrict(attrs.done),
         mentions: [...mentions],
         ...(personId !== undefined ? { personId } : {}),
@@ -86,8 +86,8 @@ function threadedCommentFrom(attrs, text, mentions) {
 }
 function mentionFrom(attrs) {
     const personId = attrs.mentionpersonId;
-    const startIndex = integerAttribute(attrs.startIndex);
-    const length = integerAttribute(attrs.length);
+    const startIndex = numInteger(attrs.startIndex);
+    const length = numInteger(attrs.length);
     if (personId === undefined || startIndex === undefined || length === undefined)
         return undefined;
     if (startIndex < 0 || length <= 0)
@@ -101,12 +101,6 @@ function mentionFrom(attrs) {
         ...(attrs.mentionId !== undefined ? { mentionId: attrs.mentionId } : {}),
     };
 }
-function integerAttribute(raw) {
-    if (raw === undefined || raw.trim() === '')
-        return undefined;
-    const value = Number(raw);
-    return Number.isInteger(value) ? value : undefined;
-}
 export function buildCommentThreads(messages, personById) {
     const threads = [];
     const commentsByHeadId = new Map();
@@ -127,14 +121,8 @@ export function buildCommentThreads(messages, personById) {
     return threads;
 }
 function anchorRef(reference) {
-    let decoded;
-    try {
-        decoded = decodeAddress(reference);
-    }
-    catch {
-        return undefined;
-    }
-    return decoded.col === undefined || decoded.row === undefined ? undefined : decoded.address;
+    const cell = tryDecodeCellRef(reference);
+    return cell === undefined ? undefined : encodeAddress(cell.col, cell.row);
 }
 function commentFrom(message, personById) {
     const author = message.personId === undefined ? undefined : personById(message.personId);
@@ -174,7 +162,7 @@ function threadedCommentXml(ref, comment, tail) {
     const date = comment.date === undefined ? '' : ` dT="${escapeAttr(comment.date)}"`;
     const person = comment.personId === undefined ? '' : ` personId="${escapeAttr(comment.personId)}"`;
     return (`<threadedComment ref="${escapeAttr(ref)}"${date}${person} id="${escapeAttr(comment.id)}"${tail}>` +
-        `<text>${escapeText(comment.text)}</text>` +
+        `<text>${escapeSpreadsheetText(comment.text)}</text>` +
         mentionsXml(comment.mentions) +
         '</threadedComment>');
 }

package/dist/io/xlsx/workbook-xml.d.ts

@@ -9,4 +9,4 @@ export declare function workbookXml(workbook: Workbook, preservedRels: readonly
 export declare const FIXED_WORKBOOK_REL_COUNT = 2;
 export declare function workbookRelsXml(sheetCount: number, hasSharedStrings: boolean, personsRelId: string | null, preservedRels: readonly PreservedWorkbookRel[], pivots: readonly PivotPlan[]): string;
 export declare function corePropsXml(properties: WorkbookProperties): string;
-export declare function appPropsXml(): string;
+export declare function appPropsXml(properties: WorkbookProperties): string;

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

@@ -232,6 +232,9 @@ export function workbookRelsXml(sheetCount, hasSharedStrings, personsRelId, pres
 }
 export function corePropsXml(properties) {
     const parts = [];
+    if (properties.title !== undefined) {
+        parts.push(`<dc:title>${escapeText(properties.title)}</dc:title>`);
+    }
     if (properties.creator !== undefined) {
         parts.push(`<dc:creator>${escapeText(properties.creator)}</dc:creator>`);
     }
@@ -253,7 +256,8 @@ export function corePropsXml(properties) {
 function w3cdtf(element, date) {
     return `<dcterms:${element} xsi:type="dcterms:W3CDTF">${date.toISOString()}</dcterms:${element}>`;
 }
-export function appPropsXml() {
+export function appPropsXml(properties) {
+    const company = properties.company === undefined ? '' : `<Company>${escapeText(properties.company)}</Company>`;
     return (XML_DECLARATION +
-        `<Properties xmlns="${NS.extProps}"><Application>ts-xlsx</Application></Properties>`);
+        `<Properties xmlns="${NS.extProps}"><Application>ts-xlsx</Application>${company}</Properties>`);
 }

package/dist/io/xlsx/worksheet-xml.d.ts

@@ -6,7 +6,7 @@ import { type SharedFormulaRole } from './shared-formulas.ts';
 import type { SharedStringTable } from './shared-strings.ts';
 import type { StyleRegistry } from './styles.ts';
 /**
- * The used-cell extent of a sheet — the top-left/bottom-right grid bounds that fold into the
+ * The used-cell extent of a sheet: the top-left/bottom-right grid bounds that fold into the
  * `<dimension>`. Rows carrying only formatting (a row height, an outline level) do not extend the
  * used range, matching how Excel records `<dimension>`, so {@link add} ignores them. A fresh extent
  * holds the `Infinity`/`-Infinity` sentinels; {@link isEmpty} reports that no used cell has been seen.
@@ -17,7 +17,7 @@ export declare class Extent {
     bottom: number;
     right: number;
     constructor(seed?: Extent);
-    /** Whether no used cell has been folded in yet — the sheet's dimension is then the lone cell `A1`. */
+    /** Whether no used cell has been folded in yet, in which case the dimension is the lone cell `A1`. */
     get isEmpty(): boolean;
     /** Fold a rendered row's used-column span into the extent. `minCol` is `Infinity` when the row
      * carried no cells (only formatting), which extends nothing. */

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

@@ -1,10 +1,10 @@
-import { decodeRange, encodeAddress, MAX_COLUMN } from '../../core/address.js';
+import { decodeRange, encodeAddress } from '../../core/address.js';
 import { DEFAULT_DATE_NUMFMT, dateToSerial } from '../../core/date.js';
 import { mangleFormula } from '../../core/formula.js';
 import { NAMED_STYLE_ID } from '../../core/internal.js';
 import { detectValueType, isDataTableFormulaValue, isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, } from '../../core/value.js';
 import { AuthoringError, InternalError } from '../../errors.js';
-import { escapeAttr, escapeText, numberText, textElement, XML_DECLARATION } from '../../xml/xml.js';
+import { escapeAttr, escapeSpreadsheetText, escapeText, numberText, textElement, XML_DECLARATION, } from '../../xml/xml.js';
 import { relativePartPath } from '../opc/part-paths.js';
 import { relationship, relationshipsPart } from '../opc/rels.js';
 import { conditionalFormattingsExtXml, conditionalFormattingsXml } from './conditional-formatting.js';
@@ -175,7 +175,7 @@ function validateMerges(sheet) {
                 top <= region.bottom &&
                 bottom >= region.top;
             if (overlaps) {
-                throw new AuthoringError(`merged range ${merge} overlaps table "${table.name}" (${table.range}) — Excel forbids a merge inside a table`);
+                throw new AuthoringError(`merged range ${merge} overlaps table "${table.name}" (${table.range}): Excel forbids a merge inside a table`);
             }
         }
     }
@@ -251,18 +251,13 @@ function sheetFormatPr(properties, outlineLevel) {
 }
 function maxColumnOutlineLevel(sheet) {
     let max = 0;
-    for (const column of sheet.columns()) {
-        if (column.index > MAX_COLUMN)
-            continue;
+    for (const column of sheet.columns())
         max = Math.max(max, column.outlineLevel ?? 0);
-    }
     return max;
 }
 function colsXml(sheet, styles) {
     const runs = [];
     for (const { index, properties } of sheet.columns()) {
-        if (index > MAX_COLUMN)
-            continue;
         const body = colBody(properties ?? {}, styles);
         if (body === null)
             continue;
@@ -410,7 +405,7 @@ function cellXml(cell, style, shared, sharedStrings) {
     }
     if (value === null)
         return `<c r="${ref}"${s}/>`;
-    throw new InternalError(`writing a ${detectValueType(value)} cell value has no arm — every CellValue kind is handled above`);
+    throw new InternalError(`writing a ${detectValueType(value)} cell value has no arm: every CellValue kind is handled above`);
 }
 function hasOwnStyle(cell) {
     return (cell.fill !== undefined ||
@@ -455,7 +450,7 @@ function formulaBodyXml(ref, s, f, result) {
         return `<c r="${ref}"${s} t="b">${f}<v>${result ? 1 : 0}</v></c>`;
     }
     if (typeof result === 'string') {
-        return `<c r="${ref}"${s} t="str">${f}<v>${escapeText(result)}</v></c>`;
+        return `<c r="${ref}"${s} t="str">${f}<v>${escapeSpreadsheetText(result)}</v></c>`;
     }
     if (isErrorValue(result)) {
         return `<c r="${ref}"${s} t="e">${f}<v>${result.error}</v></c>`;
@@ -465,5 +460,5 @@ function formulaBodyXml(ref, s, f, result) {
             return `<c r="${ref}"${s}>${f}</c>`;
         return `<c r="${ref}"${s}>${f}<v>${numberText(dateToSerial(result))}</v></c>`;
     }
-    throw new InternalError('writing a non-primitive formula result has no arm — every FormulaResult kind is handled above');
+    throw new InternalError('writing a non-primitive formula result has no arm: every FormulaResult kind is handled above');
 }

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

@@ -12,12 +12,12 @@ import type { StyleRegistry } from './styles.ts';
 import { type FlushedSheet } from './write.ts';
 /** Calculation settings applied to the streamed workbook. Mirrors the {@link Workbook} flags. */
 export interface CalcProperties {
-    /** Ask the consumer to recalculate every formula on open — the OOXML `fullCalcOnLoad` flag. */
+    /** Ask the consumer to recalculate every formula on open: the OOXML `fullCalcOnLoad` flag. */
     fullCalcOnLoad?: boolean;
 }
 type SinkOptions = {
     /**
-     * Write the package to a caller-owned {@link Writable} sink — an outbound upload, a cloud-SDK
+     * Write the package to a caller-owned {@link Writable} sink: an outbound upload, a cloud-SDK
      * stream, any destination the caller controls. {@link WorkbookStreamWriter.commit} pushes every
      * chunk into it and settles only once the sink has finished (or rejects if it errors), so a
      * caller can deterministically sequence work after the upload completes. Mutually exclusive
@@ -41,7 +41,7 @@ type SinkOptions = {
 /** Options fixed at construction that shape the whole streamed package. */
 export type WorkbookStreamWriterOptions = SinkOptions & {
     /**
-     * Pool plain string cell values into a shared-strings table rather than storing each inline — the
+     * Pool plain string cell values into a shared-strings table rather than storing each inline: the
      * same {@link WriteOptions.useSharedStrings} the buffered writer exposes. Off by default.
      */
     readonly useSharedStrings?: boolean;
@@ -58,12 +58,12 @@ export declare class StreamedRow {
     /** The cells this row materialised, for styling before it is committed. */
     get cells(): readonly Cell[];
     /** 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. */
+     * Committing twice is harmless: the second call does nothing rather than re-emitting the row. */
     commit(): void;
 }
 /**
  * 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
+ * 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 declare class WorksheetStreamWriter {
@@ -71,7 +71,7 @@ export declare class WorksheetStreamWriter {
     constructor(sheet: Worksheet, eager: boolean, styles: StyleRegistry);
     /** The sheet's name. */
     get name(): string;
-    /** The number of rows written so far — spans gaps and formatted-only rows, like the model, and
+    /** 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(): number;
     /** Append one row of values after the last used row; the cells are returned for styling. */
@@ -83,7 +83,7 @@ export declare class WorksheetStreamWriter {
      * {@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
+     * @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: number, cells: readonly Cell[]): void;
@@ -92,23 +92,23 @@ export declare class WorksheetStreamWriter {
     getCell(reference: string): Cell;
     /**
      * 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.
+     * streamed package emits the `<dataValidations>` block in its CT_Worksheet position, before
+     * `<hyperlinks>`, because both writers share one worksheet serializer.
      */
     addDataValidation(sqref: string, rule: DataValidation, options?: {
         extended?: boolean;
     }): void;
     /**
      * 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.
+     * it lands in its schema-mandated slot, after `<mergeCells>` and before `<dataValidations>` and
+     * `<hyperlinks>`, since the streamed sheet is serialized through the same path as a buffered write.
      */
     addConditionalFormatting(formatting: ConditionalFormatting): void;
     /**
      * 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`.
+     * exactly as a buffered write does: both writers share `buildPackageParts`.
      */
     addImage(imageId: number, anchor: {
         readonly tl: AnchorPoint;
@@ -116,7 +116,7 @@ export declare class WorksheetStreamWriter {
     }): void;
     /**
      * 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
+     * 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: string | AutoFilter | undefined);
@@ -147,8 +147,8 @@ export declare class WorkbookStreamWriter {
     /** Document-level metadata written to the package's core properties. */
     get properties(): 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
+     * 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.
      */

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

@@ -6,6 +6,7 @@ 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';
 export class StreamedRow {
     #cells;
@@ -145,7 +146,7 @@ export class WorksheetStreamWriter {
     }
     #assertOpen() {
         if (this.#committed) {
-            throw new AuthoringError(`worksheet "${this.#sheet.name}" is already committed — its rows are finalised and no more can be added`);
+            throw new AuthoringError(`worksheet "${this.#sheet.name}" is already committed: its rows are finalised and no more can be added`);
         }
     }
 }
@@ -178,13 +179,13 @@ export class WorkbookStreamWriter {
     }
     addImage(options) {
         if (this.#committed) {
-            throw new AuthoringError('the workbook is already committed — no more images can be registered');
+            throw new AuthoringError('the workbook is already committed: no more images can be registered');
         }
         return this.#workbook.addImage(options);
     }
     addWorksheet(name, options = {}) {
         if (this.#committed) {
-            throw new AuthoringError('the workbook is already committed — no more worksheets can be added');
+            throw new AuthoringError('the workbook is already committed: no more worksheets can be added');
         }
         const sheet = new WorksheetStreamWriter(this.#workbook.addWorksheet(name, options), this.#eager, this.#styles);
         this.#sheets.push(sheet);
@@ -244,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

@@ -16,13 +16,14 @@ export interface WriteOptions {
 /**
  * {@link WriteOptions} plus the streaming writer's internal wiring, so a buffered caller's options
  * object can never carry fields meant only for {@link WorkbookStreamWriter}'s own use. Not exported
- * from the public barrel — {@link buildPackageParts} is the only consumer outside this module.
+ * from the public barrel: {@link WorkbookStreamWriter} is the only caller that fills these fields,
+ * and it reaches them through {@link buildPackageParts}.
  */
 export interface InternalWriteOptions extends WriteOptions {
     /**
      * The style registry to intern into, in place of a freshly-seeded one. The streaming writer
      * serialises each committed row eagerly (freeing its cells), so those rows' style ids must be
-     * assigned by the very same registry that later emits `xl/styles.xml` — otherwise the ids in the
+     * assigned by the very same registry that later emits `xl/styles.xml`; otherwise the ids in the
      * pre-rendered rows would not match the styles part. When omitted the buffered path seeds its own,
      * so its output is unchanged.
      */
@@ -37,6 +38,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,19 +49,19 @@ 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 and 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
  * 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
+ * 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};
+ * @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}.
@@ -71,8 +76,8 @@ export declare function writeXlsxAsync(workbook: Workbook, options?: WriteOption
 export declare function createStyleRegistry(workbook: Workbook): StyleRegistry;
 /**
  * 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
+ * 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.
  *