@shbernal/ts-xlsx 1.0.0

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

@@ -0,0 +1,9 @@
+import { type Table, type TableOptions } from '../../core/table.ts';
+export declare function tableXml(table: Table, id: number): string;
+/**
+ * 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 declare function parseTable(xml: string): TableOptions | undefined;

package/dist/io/xlsx/tables.js

@@ -0,0 +1,208 @@
+// 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";
+import { localName, parseXml } from "../../xml/xml-read.js";
+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"';
+    }
+    else if (table.totalsRowShown !== undefined) {
+        totals = ` totalsRowShown="${table.totalsRowShown ? '1' : '0'}"`;
+    }
+    else {
+        totals = '';
+    }
+    const autoFilter = table.autoFilterRef !== undefined ? `<autoFilter ref="${table.autoFilterRef}"/>` : '';
+    const columns = table.columns.map((column, i) => tableColumnXml(column, i + 1)).join('');
+    return (XML_DECLARATION +
+        `<table xmlns="${NS.main}" id="${id}" name="${name}" displayName="${displayName}" ` +
+        `ref="${table.range}"${headerRowCount}${totals}>` +
+        autoFilter +
+        `<tableColumns count="${table.columns.length}">${columns}</tableColumns>` +
+        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;
+    let attrs = '';
+    if (style.name !== undefined)
+        attrs += ` name="${escapeAttr(style.name)}"`;
+    attrs +=
+        boolAttr('showFirstColumn', style.showFirstColumn) +
+            boolAttr('showLastColumn', style.showLastColumn) +
+            boolAttr('showRowStripes', style.showRowStripes) +
+            boolAttr('showColumnStripes', style.showColumnStripes);
+    return `<tableStyleInfo${attrs}/>`;
+}
+function tableColumnXml(column, id) {
+    let attrs = `id="${id}" name="${escapeAttr(column.name)}"`;
+    if (column.totalsRowLabel !== undefined) {
+        attrs += ` totalsRowLabel="${escapeAttr(column.totalsRowLabel)}"`;
+    }
+    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.
+    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;
+                    if (attrs.headerRowCount !== undefined)
+                        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;
+                case 'autoFilter':
+                    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;
+                    if (attrs.showFirstColumn !== undefined)
+                        captured.showFirstColumn = parseOoxmlBool(attrs.showFirstColumn);
+                    if (attrs.showLastColumn !== undefined)
+                        captured.showLastColumn = parseOoxmlBool(attrs.showLastColumn);
+                    if (attrs.showRowStripes !== undefined)
+                        captured.showRowStripes = parseOoxmlBool(attrs.showRowStripes);
+                    if (attrs.showColumnStripes !== undefined) {
+                        captured.showColumnStripes = parseOoxmlBool(attrs.showColumnStripes);
+                    }
+                    style = captured;
+                    break;
+                }
+                case 'tableColumn': {
+                    if (attrs.name === undefined)
+                        break;
+                    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;
+                    }
+                    columns.push(column);
+                    break;
+                }
+                case 'totalsRowFormula':
+                    inTotalsFormula = true;
+                    totalsFormula = '';
+                    break;
+            }
+        },
+        onText(text) {
+            if (inTotalsFormula)
+                totalsFormula += text;
+        },
+        onClose(elementName) {
+            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;
+        },
+    });
+    if (name === undefined || ref === undefined || columns.length === 0)
+        return undefined;
+    const { top, left, bottom } = decodeRange(ref);
+    if (top === undefined || left === undefined || bottom === undefined)
+        return undefined;
+    const headerRow = headerRowCount !== 0;
+    const totalsRow = totalsRowCount > 0;
+    const dataRows = bottom - top + 1 - (headerRow ? 1 : 0) - (totalsRow ? 1 : 0);
+    const options = {
+        name,
+        displayName: displayName ?? name,
+        ref: encodeAddress(left, top),
+        columns,
+        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)
+        options.style = style;
+    return options;
+}

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

@@ -0,0 +1,102 @@
+import { type CommentThread, 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;
+    readonly displayName: string;
+    /** Identity-provider handle, `S::<email>::<tenant-guid>` for an AzureAD account. */
+    readonly userId?: string;
+    /** Identity provider, e.g. `AD`. */
+    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.
+ *
+ * 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.
+ */
+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 interface ParsedThreadedComment {
+    /** A1 reference of the cell the whole thread anchors to; every message of a thread repeats it. */
+    readonly ref: string;
+    /** Brace-wrapped GUID identifying this message, and the `parentId` its replies carry. */
+    readonly id: string;
+    /** The author's {@link ParsedPerson.id}. Absent in a file that recorded no author. */
+    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
+     * string spares the reader from inventing a zone the file never stated.
+     */
+    readonly date?: string;
+    readonly text: string;
+    /** The thread head's {@link ParsedThreadedComment.id}; absent iff this message *is* the head. */
+    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
+     * `false` here means "did not say", not "not resolved".
+     */
+    readonly done: boolean;
+    /** The `<mentions>` this message carries, in document order; empty when it names no one. */
+    readonly mentions: readonly ParsedMention[];
+}
+/**
+ * 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 declare function parsePersons(xml: string): ParsedPerson[];
+/**
+ * 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 declare function parseThreadedComments(xml: string): ParsedThreadedComment[];
+/**
+ * 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 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
+ * {@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 declare function threadedCommentsXml(threads: readonly CommentThread[]): string;
+/**
+ * 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 declare function personsXml(persons: readonly Person[]): string;

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

@@ -0,0 +1,308 @@
+// 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;
+            if (id === undefined)
+                return;
+            persons.push({
+                id,
+                displayName: displayName ?? '',
+                ...(userId !== undefined ? { userId } : {}),
+                ...(providerId !== undefined ? { providerId } : {}),
+            });
+        },
+    });
+    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;
+    let mentions = [];
+    let inText = false;
+    let text = '';
+    parseXml(xml, {
+        onOpen(name, attrs) {
+            const local = localName(name);
+            if (local === 'threadedComment') {
+                open = attrs;
+                text = '';
+                mentions = [];
+            }
+            else if (local === 'text' && open !== undefined) {
+                inText = true;
+            }
+            else if (local === 'mention' && open !== undefined) {
+                const mention = mentionFrom(attrs);
+                if (mention !== undefined)
+                    mentions.push(mention);
+            }
+        },
+        onText(chunk) {
+            if (inText)
+                text += chunk;
+        },
+        onClose(name) {
+            const local = localName(name);
+            if (local === 'text') {
+                inText = false;
+            }
+            else if (local === 'threadedComment') {
+                if (open !== undefined) {
+                    const message = threadedCommentFrom(open, text, mentions);
+                    if (message !== undefined)
+                        messages.push(message);
+                }
+                open = undefined;
+                text = '';
+                mentions = [];
+            }
+        },
+    }, { closeEmptyElements: THREADED_COMMENT_EMPTY_CLOSES });
+    return messages;
+}
+function threadedCommentFrom(attrs, text, mentions) {
+    const { ref, id, personId, dT, parentId } = attrs;
+    if (ref === undefined || id === undefined)
+        return undefined;
+    return {
+        ref,
+        id,
+        text,
+        done: boolStrict(attrs.done),
+        mentions: [...mentions],
+        ...(personId !== undefined ? { personId } : {}),
+        ...(dT !== undefined ? { date: dT } : {}),
+        ...(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)
+        return undefined;
+    return {
+        personId,
+        startIndex,
+        length,
+        ...(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);
+        const siblings = message.parentId === undefined ? undefined : commentsByHeadId.get(message.parentId);
+        if (siblings !== undefined) {
+            siblings.push(comment);
+            continue;
+        }
+        const ref = anchorRef(message.ref);
+        if (ref === undefined)
+            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 {
+        decoded = decodeAddress(reference);
+    }
+    catch {
+        return undefined;
+    }
+    return decoded.col === undefined || decoded.row === undefined ? undefined : decoded.address;
+}
+function commentFrom(message, personById) {
+    const author = message.personId === undefined ? undefined : personById(message.personId);
+    return {
+        id: message.id,
+        text: message.text,
+        mentions: message.mentions.map((mention) => mentionOf(mention, personById)),
+        ...(author !== undefined ? { author } : {}),
+        ...(message.personId !== undefined ? { personId: message.personId } : {}),
+        ...(message.date !== undefined ? { date: message.date } : {}),
+    };
+}
+function mentionOf(mention, personById) {
+    const person = personById(mention.personId);
+    return {
+        personId: mention.personId,
+        startIndex: mention.startIndex,
+        length: mention.length,
+        ...(person !== undefined ? { person } : {}),
+        ...(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;
+        if (head === undefined)
+            return [];
+        return [
+            threadedCommentXml(thread.ref, head, thread.resolved ? ' done="1"' : ''),
+            ...replies.map((reply) => threadedCommentXml(thread.ref, reply, ` parentId="${escapeAttr(head.id)}"`)),
+        ];
+    });
+    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)}"`;
+    return (`<threadedComment ref="${escapeAttr(ref)}"${date}${person} id="${escapeAttr(comment.id)}"${tail}>` +
+        `<text>${escapeText(comment.text)}</text>` +
+        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 [
+            `<mention mentionpersonId="${escapeAttr(personId)}" mentionId="${escapeAttr(mentionId)}"` +
+                ` startIndex="${startIndex}" length="${length}"/>`,
+        ];
+    });
+    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)}"`;
+        const providerId = person.providerId === undefined ? '' : ` providerId="${escapeAttr(person.providerId)}"`;
+        return (`<person displayName="${escapeAttr(person.displayName)}"` +
+            ` id="${escapeAttr(person.id)}"${userId}${providerId}/>`);
+    });
+    return `${XML_DECLARATION}<personList xmlns="${THREADED_COMMENTS_NS}">${entries.join('')}</personList>`;
+}

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

@@ -0,0 +1,12 @@
+import type { Workbook, WorkbookProperties } from '../../core/workbook.ts';
+import type { PivotPlan, PreservedPartPlan, PreservedRootReferencePlan, PreservedWorkbookReferencePlan, TablePlan } from './package-plan.ts';
+export type PreservedWorkbookRel = PreservedWorkbookReferencePlan & {
+    readonly relId: string;
+};
+export declare function contentTypesXml(sheetCount: number, tables: readonly TablePlan[], commentNumbers: readonly number[], drawingNumbers: readonly number[], printerSettingsNumbers: readonly number[], mediaExtensions: readonly string[], hasSharedStrings: boolean, preservedParts: readonly PreservedPartPlan[], pivots: readonly PivotPlan[], preservedWorkbookRefs: readonly PreservedWorkbookReferencePlan[], threadedCommentNumbers: readonly number[], hasPersons: boolean): string;
+export declare function rootRelsXml(rootRefs: readonly PreservedRootReferencePlan[]): string;
+export declare function workbookXml(workbook: Workbook, preservedRels: readonly PreservedWorkbookRel[], pivots: readonly PivotPlan[]): string;
+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;